Recently, I came across a blog post by Tony Hirst on computational essays and how they can be used to facilitate learning. Hirst was reflecting on an earlier blog post by Stephen Wolfram on what defines a computational essay. Computational essays are, as paraphrased from Hirst and Wolfram, a mixture of plain language, computer input, and computer output allowing the user to interweave narrative with code and the output from that code.
In reading the blog post by Hirst, I realized that I have been using computational essays on accident for several years. My first exposure to them was many years ago when using Mathematica in college. At the time, I didn’t quite understand the interface and soon moved to R when it was introduced to me in 2009. The release of R Markdown a few years later is when I truly began thinking in terms of computational essays.
As with using Mathematica, I didn’t quite understand the purpose of R Markdown at first. My first real use for R Markdown was for some calculations I was doing on the Stark effect in Rubidium. I found that interweaving the calculation code with some plain text explanations helped me keep track of the choices I was making in the code. More importantly, it provided documentation if I needed to share the code with anyone else in my lab. Prior to this, the documentation for my calculations was a mix of comments to explain the specifics of the code and separate documents (often handwritten) to explain the reasoning. Now I could combine them in the same place!
Soon after I started using R Markdown, I discovered that the file can be compiled as an html file. This allowed me to truly start thinking in terms of computational essays. Now, instead of sending my advisor an e-mail with a bunch of figures I could send a single html file with the figures and explanation combined in the same document. I also took that same html file and used it to present analysis results during lab meetings. Again, this put all of my figures in the same place along with descriptions of the analysis being done.
The only problem with a computational essay is the additional time it takes to prepare one. This is, of course, a feature as well. There is additional time required because you have to actually describe what you are doing for an audience that hasn’t spent every day for a month with the data.
This led me to one of my biggest revelations from using computational essays and a general trend I noticed while in graduate school. Any document that you plan to show someone who isn’t you has to be clear and concise. Figures with labels automatically generated from the data set might be fine for the person making the figure, but it will certainly be unintelligible for anyone reading the document. The document does not need to be journal publication ready, but it does need to be polished enough so that the author does not have to walk their audience through in person.
So, take the time to polish your work. Even if you think your audience will understand the shortcuts you’ve taken, that little bit of extra effort goes a long way to communicating your ideas.