A template for reproducible papers

At the PINGA lab, we have been experimenting with ways to increase the reproducibility of our research by publishing the git repositories that accompany our papers. You can find them on our Github organzation. I've synthesized the experience of the last 4 years into a template in the pinga-lab/paper-template repository.

Screenshot of the paper-template Github repository.

The template reflects the tools we've been using and the type of research that we do:

This certainly won't fit everyone's needs but I hope that you can at least use a few bits and pieces for inspiration. Of course, the template code is open-source (BSD license) and you are free to reuse it however you like. The template includes a sample application to climate change data, complete with a Python package, automated tests, an analysis notebook, a notebook that generates the paper figure, raw data, and a LaTeX text. Everything, from compilation to building the final PDF, can be done with a single make command.

Screenshot of running "make" in the paper-template with the final paper PDF and a Jupyter notebook.

We've been using different versions of this template for a few years and I've been tweaking it to address some of the difficulties we encountered along the way.

The latest update addresses all of these pain points. The main features of the new template are:

This last feature is my favorite. For example, the notebook code/notebooks/estimate-hawaii-trend.ipynb has the following code:

tex = r"""
% Generated by code/notebooks/estimate-hawaii-trend.ipynb
\newcommand{{\HawaiiLinearCoef}}{{{linear:.3f} C}}
\newcommand{{\HawaiiAngularCoef}}{{{angular:.3f} C/year}}
""".format(linear=trend.linear_coef, angular=trend.angular_coef)

with open('../../manuscript/hawaii_trend.tex', 'w') as f:
    f.write(tex)

It defines the LaTeX commands \HawaiiLinearCoef and \HawaiiAngularCoef that can be used in the paper to insert the values estimated by the Python code. The commands are saved to a .tex file that can be included in the main manuscript.tex. Since this file is generated by the code, the values are guaranteed to be up-to-date.

If you want to use the template to start a new project:

  1. Create a new git repository:

    mkdir mypaper
    cd mypaper
    git init
    
  2. Pull in the template code:

    git pull https://github.com/pinga-lab/paper-template.git master
    
  3. Create a new repository on Github.

  4. Push the template code to Github:

    git remote add origin https://github.com/USER/REPOSITORY.git
    git push -u origin master
    
  5. Follow the instruction in the README.md.

Alternatively, you can use the "Import repository" option on Github.

Screenshot of the Github page for importing code from an existing repository.

I hope that this template will be useful to people outside of our lab. There is definitely still room for improvement and I'm looking forward to trying it out on my next project.

What other features would you like to see in the template? Let me know in the comments (or better yet, submit a pull request). I'd love to know about your experiences and workflows for computational papers.


Comments? Leave one below or let me know on Twitter @leouieda.
Found a typo/mistake? Send a fix through Github and I'll happily merge it (plus you'll feel great because you helped someone). All you need is an account and 5 minutes!

More from the blog

Related pages