HyperScience

I have been playing around with reproducible research in org-mode. As an example for students, I have produced a paper written entirely in org-mode and containing all the required calculations within the document itself. The diagram was made using DITAA and the values were calculated and plotted using calls to elisp and python routines. The paper is formatted as if if were a paper in the Springer Journal Shock Waves, as I wanted to demonstrate the ease of using org-mode with a \(\LaTeX\) style for journal papers. It should be possible, though not necessarily straightforward, to change the style to suit whatever form of journal paper was required. I just chose this one because I like the Springer journal format and fonts.

The paper is on the eternal problem of whether your tea will be cooler after 10 minutes if you mix the milk and the tea immediately and then waiting 10 minutes or by waiting and then adding the tea. You’ll have to read the paper to find out the answer! This is a simple enough problem that allows for a demonstration of how equations and figures are generated and presented using the org-mode markup features.

It was an interesting experience to write this paper. It took me around 2 days of full-time work to get it up and running, but now that I’ve done it, the process should be much quicker for an actual paper. It was not always straightforward to get working either: I found the referencing of figures and tables was hit-and-miss. I’m not sure whether this is normal, or something to do with my configuration, but I often found myself looking at and compiling the .tex files produced by org to determine where my labels ended up and why they were sometimes not found. But eventually I did get it working.

My knowledge of python was not really good enough to allow me to do much in the way of calculating and plotting data, and I was not able to work out how to call a python routine to put numbers in a table. I therefore decided to do most of the table calculations in elisp, where the interface to the org-table is quite seamless. Although I find mathematics in lisp a little awkward, I was able to get it all working with a minimum of fuss, and elisp is pretty easy to debug in emacs.

It’s certainly very neat to be able to populate the text with computed numbers that can change whenever the input parameters for the paper change. And having the plots automatically update when the data is changed is also wonderful. For me, this is the way to properly write a paper, even though there is certainly more groundwork that needs to be done to get the paper written. It may not also work so well for papers where there is a lot of computational work, or where commercial gui-based software is used. But most of my papers contain only small calculations using scripting languages called from the command-line, and org-mode is perfect for that workflow.

An annoyance that I was not expecting is that for the Springer journal file, the abstract occurs in the preamble, so I could not just include a bunch of #+LATEX_HEADER: commands. Instead I needed to use a \input command to include the \(\LaTeX\) within the document.

My plan is for this paper to form a template for a document on how to set up emacs and org-mode from scratch in a new linux distribution, so any student gets a head-start in how to make a reproducible research paper. I could have added more bells and whistles, but I deliberately chose a minimal useful set to not cause unnecessary confusion.

Here is the pdf of the paper

Here is the org-mode file

Here is the bibliography file

Here is the \(\LaTeX\) header file

Because of the wordpress limits on file extensions I had to change all but the pdf file to a .txt extension.

Sometime soon I plan to write the installation from scratch document that allows one to go from a new installation of ubuntu to being able to produce this document.