Skip to content

Latest commit

 

History

History
175 lines (152 loc) · 8.61 KB

index.org

File metadata and controls

175 lines (152 loc) · 8.61 KB
Raw

Introduction, producing replicable articles and managing a laboratory notebook with emacs/org-mode

This seminar took place on March 7, 2016. The link to the video is below. Do not forget to check the section on software installation if you want to test yourself the demoed tools.

Table of Contents

Practical information

Arnaud Legrand gave a general introduction on reproducible research.

Webcast/Video

Here is the link to the video. If you have any trouble with the flashplayer, here is a direct link to the mpeg4 video. The slides are available here.

To interact during the presentation (questions, comments), we used this pad.

Persons in charge

  • Grenoble: Arnaud Legrand, Frédéric Desprez
  • Bordeaux: Luka Stanisic, Emmanuel Agullo, Nicolas P. Rougier, Ludovic Courtès
  • Rennes: Martin Quinson
  • Paris: Roberto Di Cosmo
  • Toulouse: Matthieu Roy
  • TU Vienne: Louis-Claude Canon
  • Orléans: Konrad Hinsen

Locations

  • Grenoble: MJK (Arnaud Legrand), GIANT (Frédéric Desprez), Inria A103 (Pierre Neyron), …
  • Lyon: ENS Lyon, salle du conseil (Loris Marchal)
  • Bordeaux: Ada Lovelace room (Ludovic Courtès)
  • Rennes: salle visio Bréhat (Martin Quinson)
  • Paris: salle visio Cantor (Roberto Di Cosmo)
  • …

Practical Session Requirements

We will explain the audience how to create and manage replicable articles and give advice on how to manage a laboratory notebook on a daily basis.

To benefit from this presentation, we recommend the audience to install the software described in each section. In particular, we want a recent version of emacs with ESS (for R) and AucTeX (for LaTeX). Finally, you will need a working LaTeX and R environment to build a replicable article.

Once you’re done with the software installation that are specific to your operating system, go to this section.

Installing emacs, ess, auctex, …

Mac OS X

  • Option 1: If you already use brew, simply do the following 
    brew update
brew install emacs [--with-cocoa]
brew linkapps emacs
brew tap homebrew/science
brew install ess
brew install auctex # The name may be slightly more complicated here
brew install wget
  • Option 2: Install the .dmg file from http://vgoulet.act.ulaval.ca/en/emacs/mac/. In that case you may have several versions of emacs installed on your machine and launching emacs from a terminal may not run the one you just installed. If anyone know how to get rid of this…

Windows

Install the .exe file from http://vgoulet.act.ulaval.ca/emacs/windows/.

Linux

If you’re running a debian system, simply do (as root):

apt-get update ; apt-get install emacs org-mode ess r-base auctex

Then make sure you have a sufficiently recent version

emacs --version 2>&1 | head -n 1
GNU Emacs 24.5.1

I’d say you want at least an emacs 24.4 (October 2014) or 24.5 (April 2015) to be out of troubles. Emacs 24.3 was released in March 2013, i.e., three years ago, which is quite old.

Likewise, you’ll want to check you have a recent version of org-mode:

emacs -batch --funcall "org-version" 2>&1 | grep version
Org-mode version 8.3.1 (8.3.1-dist @ /usr/share/emacs24/site-lisp/org-mode/)

The current latest version is actually 8.3.3 but you’ll want at least a version 8.2.

A stub of replicable article

Remember, you need a working LaTeX and R environment. If you can’t open a terminal and run the commands R and pdflatex, you will not be able to generate this document. You may still read the source (article.org) and understand how it works though.

Download the archive, untar it and simply make to generate the article. You should then be able to open the resulting article.

wget --no-check-certificate -O replicable.tgz https://github.com/alegrand/RR_webinars/raw/master/1_replicable_article_laboratory_notebook/replicable/replicable.tgz
tar zxf replicable.tgz; cd replicable; make ; evince article.pdf

If the make command fails (especially on Mac), it may be because emacs or something else is not correctly installed. In that case, open the article directly with the following command:

emacs -q --eval "(setq enable-local-eval t)" --eval "(setq enable-local-variables t)" --eval "(setq org-export-babel-evaluate t)" article.org

and export it to pdf with the following shortcut: C-c C-e l o

If it still doesn’t work and emacs complains about not finding ESS, it may be because you installed ESS in your home instead of system-wide. In that case, try to remove the -q in the previous command line to load your personal emacs configuration.

Finally, when you’ll be tired of always reexecuting all the source code when exporting, simply modify the last eval line of article.org according to the comment.

Reproducible research emacs configuration for maintaining your laboratory notebook

Step 1: Prepare your journal

Create an org/ directory in the top of your home:

mkdir -p ~/org/

Then copy this file in the ~/org/ directory. This file will be your laboratory notebook and all the notes you will capture with C-c c (this will be explained in the tutorial) will go automatically go in this file. I populated the first entry of this notebook with many emacs shortcuts that I will demonstrate.

Step 2: Set up Emacs configuration

  • Option 1 (if you’re convinced and want my configuration for the rest of your life): Backup you own .emacs (who knows what may happen?) if you have one and replace it with the content of this file.
  • Option 2 (if you only want to give a try for today): Get this file and launch emacs with this specific configuration with the following command: emacs -q -l init.el

Step 3: Check whether the installation is working or not

Open a new instance of Emacs and open a foo.org file. Copy the following lines in this file:

#+begin_src sh :session foo :results output :exports both
ls -la
#+end_src

Put your cursor inside this code block and execute it with the following command: C-c C-c (If you are not familiar with Emacs commands, this one means ’Ctrl + C’ twice)

A #+RESULTS: block with the result of the command should appear if it worked.

In the tutorial we will show you the main features and shortcuts of emacs/org-mode that will help you maintain your laboratory notebook (the journal.org) and benefit from literate programming. The list of features we will demonstrate is in the first entry of your labbook.