Skip to content

Latest commit

 

History

History
211 lines (187 loc) · 11 KB

index.org

File metadata and controls

211 lines (187 loc) · 11 KB

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.

video_thn.png

To interact during the presentation (questions, comments), we used this pad that we keep for the record.

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

Edit: This section was edited on February 2018 and on July 2019 to keep it up-to-date with more recent versions of org-mode and others. Feel free to navigate in the history to obtain the version originally used in March 2016.

Warning: I try maintain with some colleagues an extended, up-to-date and somehow similar set of instructions here for the Reproducible Research MOOC. This is what I really recommend to follow now.

Warning’: This tuturial relies on org-mode 9.

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: Install the .dmg file from Vincent Goulet: https://vigou3.github.io/emacs-modified-macos/. It ships with recent versions:
    • Emacs 25.3
    • ESS 17.11
    • org-mode 9.1.6

    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…

  • Option 2: 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

Windows

Install the .exe file from Vincent Goulet: https://vigou3.github.io/emacs-modified-windows/. It ships with recent versions:

  • Emacs 25.3
  • ESS 17.11
  • org-mode 9.1.6

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 25.2.2

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 9.0.3 (9.0.3-dist @ /usr/share/emacs25/site-lisp/org-mode/)

You really want to make sure you do not rely on org-mode 8, which is becoming deprecated. If you have to stay with this particular version, browse the history of this repository to obtain emacs configuration and files that are compatible with org-mode 8.

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. The article downloads the corresponding LaTeX packages so you also need to have a working wget command (alternatively, you can use curl). 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. This is summarized in the following command:

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)"  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, just look for the following line in article.org:

# #+PROPERTY: header-args :eval never-export

If you remove the #  in the beginning of the line, it will not be a comment anymore and will indicate org-mode to stop evaluating every chunck of code when exporting.

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 shell :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.

A few information on how to play with jupyter/ipython

Check this entry.

A few information on how to play with Rstudio

Check this entry.