From 6954e2599816062e2624bbb9a2a64f1eeac47b46 Mon Sep 17 00:00:00 2001 From: Arnaud Legrand Date: Thu, 19 Jul 2018 14:27:06 +0200 Subject: [PATCH] Automatically generated html versions --- module2/ressources/emacs_orgmode.html | 677 ++++++++++++++++++++++++++ module2/ressources/jupyter.html | 494 +++++++++++++++++++ module2/ressources/rstudio.html | 472 ++++++++++++++++++ 3 files changed, 1643 insertions(+) create mode 100644 module2/ressources/emacs_orgmode.html create mode 100644 module2/ressources/jupyter.html create mode 100644 module2/ressources/rstudio.html diff --git a/module2/ressources/emacs_orgmode.html b/module2/ressources/emacs_orgmode.html new file mode 100644 index 0000000..b86497a --- /dev/null +++ b/module2/ressources/emacs_orgmode.html @@ -0,0 +1,677 @@ + + + + + + + +Emacs/org-mode + + + + + + +
+

Emacs/org-mode

+ + +
+

Installing emacs, org-mode, ess, and auctex.

+
+
+
+

OS-specific installation procedure

+
+
+
+

Linux (Debian, Ubuntu)

+
+

+We provide here only instructions for debian-based distributions. Feel +free to contribute to this document to provide up-to-date information +for other distributions (e.g.n redhat, fedora). +

+ +

+Today, the stable versions of the most common distributions provide +recent enough versions of emacs and org-mode: +

+ +

+If your distribution is older than this, well, it may be a good time +for upgrading… +

+ +

+Simply run (as root): +

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

+Then make sure you have a sufficiently recent version of emacs. +

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

+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.1.11 (9.1.11-dist @ /usr/share/emacs/25.2/site-lisp/elpa/org-9.1.11/)
+
+
+ +

+The version numbers you get will depend on the distribution you are +running. You really want to make sure you do not rely on org-mode 8, +which is now deprecated. +

+
+
+
+

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 26.1
      • +
    • Org-mode 9.1.13
      • +
    • ESS 17.11
      • +
    +

    +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 26.1
    • +
  • Org-mode 9.1.13
    • +
  • ESS 17.11
    • +
+
+
+
+
+

A simple "reproducible research" emacs configuration

+
+

+Emacs comes with very basic default configuration and it appears like +everyone has its own taste. You will for example find here several +default Emacs configurations that reflect the preferences of their +creators. Likewise the configuration of Org-Mode is incredibly +flexible (see for example the org-mode website for more +references). In the context of this MOOC, we propose you a relatively +minimalistic one that is rather "reproducible research" oriented by +adding a few org-mode specific configurations. +

+
+ +
+

Step 0: Backup and download our configuration

+
+

+The procedure we propose will wipe your already existing custom emacs +configuration if you already have one. You should thus beforehand make +a backup of ~/.emacs and of ~/.emacs.d/init.el (if these file +exists). +

+ +

+Then download this archive and uncompress it. It contains the +following files and we will refer to them in the following: +

+ +
+rr_org/init.el
+rr_org/journal.org
+
+
+
+
+ +
+

Step 1: Prepare your journal

+
+

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

+
+
mkdir -p ~/org/
+
+
+

+Then copy rr_org/journal.org file in your ~/org/ directory. This +file will be your laboratory notebook and all the notes you will +capture with C-c c will go automatically go in this file. The first +entry of this notebook is populated with many emacs shortcuts that you +should give a try. +

+
+
+
+

Step 2: Set up Emacs configuration

+
+

+Copy rr_org/init.el in your ~/.emacs.d/ directory. +

+ +

+Alternatively, if you do not want to mess with your already existing +emacs configuration, you may launch emacs with this specific +configuration with the following command: emacs -q -l rr_org/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 video, we already have demonstrated the main features and +shortcuts of emacs/org-mode that will help you maintain a document and +benefit from literate programming. The list of features and shortcuts +is demonstrated in the first entry of your labbook. +

+
+
+
+

Step 4: Open and play with your journal:

+
+

+In step 1, you were told to create an journal in +~org/journal.org. First you probably want to make sure this file is +backed up in a revision control system like git. We leave it up to set +this up but if you have any trouble, feel free to ask on the FUN +forums. +

+
+
+
+
+
+

Emacs Tips and tricks

+
+
+
+

Cheat-sheets

+
+

+Learning emacs and org-mode can be difficult as there is an inordinate +amount of shortcuts. Many people have thus come up with +cheat-sheats. Here is a selection in case it helps: +

+
+ + +
+
+

Video tutorials

+
+

+For those of you who prefer video explanations, here is a Youtube +channel with many step by step emacs tutorials. +

+
+
+
+

Additional useful emacs packages

+
+
+
+

Company-mode

+
+

+Company-mode is a text completion framework for Emacs. It allows to +have smart completion in emacs for the most common languages. If you +feel this is needed, you should follow the instructions from the +official webpage: http://company-mode.github.io/ +

+
+
+
+

Magit

+
+

+Magit is an emacs interface for Git. It is very powerfull and we use +it on a daily basis but you should definitely understand what git does +behind the scene beforehand. If you feel this would be useful for you, +you should follow the instructions from here: +https://www.emacswiki.org/emacs/Magit +

+
+
+
+ +
+
+

A replicable article

+
+
+
+

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 ### Fix the broken URL
+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 +chunk of code when exporting. +

+
+
+
+
+
+

Date: June, 2018

+

Author: Arnaud Legrand

+

Created: 2018-07-19 jeu. 14:26

+

Validate

+
+ + diff --git a/module2/ressources/jupyter.html b/module2/ressources/jupyter.html new file mode 100644 index 0000000..71405a3 --- /dev/null +++ b/module2/ressources/jupyter.html @@ -0,0 +1,494 @@ + + + + + + + +Rstudio + + + + + + +
+

Rstudio

+ + +
+

Interacting with gitlab

+
+
+

+This section needs some love. +

+
+ +

+As you may have seen from the videos, we provide two buttons to sync +with gitlab. Indeed, even if you recover your files when you log back +into fun, the jupyter runs on a different machine than the gitlab +server and you need to commit your notebook every time you have made a +significant step. This is also the only way to really make it public +and to share your notebook with others. +

+
+
+
+

Additional Jupyter resources or tricks

+
+
+
+

Tips and tricks

+
+

+The following webpage lists several Jupyter tricks (in particular, it +illustrates many Ipython magic commands) that should improve your +efficiency (note that this blog post is about two years old so some of +the tricks may have been integrated in the default behavior of jupyter +now). +

+
+
+
+

Running R and Python in the same notebook

+
+

+The best solution to this is to install rpy2. On my machine, I have +installed the python3-rpy2 debian package with apt-get install. An +other alternative consists in going through the python package manager +with +

+
+
pip install rpy2
+
+
+

+Then you'll be able to use both languages in the same notebook by: +

+
    +

  1. +Loading rpy2: +

    +
    +
    %load_ext rpy2.ipython
+
    +
    2. +

  2. +Using the %R Ipython magic: +

    +
    +
    %R 
+summary(cars)
+
    +
    +

    +Python objects can then even be passed to R as follows (assuming df +is a pandas dataframe: +

    +
    +
    %%R -i df
+plot((df)
+
    +
    3. +
+
+
+
+

Exporting a notebook

+
+

+Obviously, you can convert to html or pdf using the using the File > +Download as > HTML (or PDF) menu option. This can also be done from +the command line with the following command: +

+ +
+
ipython3 nbconvert --to pdf Untitled.ipynb
+
+
+ +

+If you want to use a specific style, then the nbconvert exporter +should be customised. This is discussed and demoed here. We encourage +you to simply read the doc of nbconvert. +

+ +

+Instead of going directly through LaTeX and playing too much with the +nbconvert exporter, an other option consists in exporting to Markdown +and playing with pandoc. Both approaches work, it's rather a matter of +taste. +

+
+
+
+
+

Installing jupyter or jupyter hub on your own machine

+
+
+
+

Installing jupyter

+
+

+Here is what you should install: +

+
+
sudo apt-get install jupyter-notebook python3-pip python3-matplotlib python3-numpy
+
+
+ +

+On my machine, I got the version 5.4.1: +

+
+
jupyter-notebook --version
+
+
+ +
+5.4.1
+
+
+ +

+The ipython notebook can then be run with the following command: +

+
+
jupyter-notebook
+
+
+
+
+
+

Using R

+
+

+If you also want to have the R kernel in jupyter, follow these +instructions. +

+ +

+Alternatively, you can install rpy2 (see the Running R and Python in +the same notebook section). +

+
+
sudo apt-get python3-rpy2
+
+
+
+
+
+

Exporting your notebooks with latex

+
+

+Here is what I had to install to make sure the notebook export via +latex works: +

+
+
sudo apt-get install wkhtmltopdf
+sudo apt-get install texlive-xetex
+
+
+
+
+
+

Interacting with gitlab

+
+

+Here is our jupyter extension that allows to git push/pull from the +notebooks: +

+
+
jupyter nbextension install https://raw.githubusercontent.com/brospars/nb-git/master/nb-git.js
+jupyter nbextension enable nb-git
+
+
+
+
+
+

Interesting extensions

+
+
    +

  • +Code folding +

    +
    +
    pip3 install jupyter_contrib_nbextensions
+# jupyter contrib nbextension install --user # not done yet
+
    +
    • +

  • +Hiding code +

    +
    +
    sudo pip3 install hide_code
+sudo jupyter-nbextension  install --py hide_code
+jupyter-nbextension  enable --py hide_code
+jupyter-serverextension enable --py hide_code
+
    +
    • +
+
+
+
+

Installing jupyterhub

+
+
+

+Benoit may give a few hints on this. +

+
+
+
+
+
+
+

Date: June, 2018

+

Author: Arnaud Legrand

+

Created: 2018-07-19 jeu. 14:26

+

Validate

+
+ + diff --git a/module2/ressources/rstudio.html b/module2/ressources/rstudio.html new file mode 100644 index 0000000..40ce538 --- /dev/null +++ b/module2/ressources/rstudio.html @@ -0,0 +1,472 @@ + + + + + + + +Rstudio + + + + + + +
+

Rstudio

+ + +
+

Installing Rstudio

+
+
+
+

Linux (debian, ubuntu)

+
+

+We provide here only instructions for debian-based distributions. Feel +free to contribute to this document to provide up-to-date information +for other distributions (e.g.n redhat, fedora). +

+ +

+Today, the stable versions of the most common distributions provide +recent enough versions of emacs and org-mode: +

+ +

+If your distribution is older than this, well, it may be a good time +for upgrading… +

+
+ +
+

Installing R

+
+

+Beforehand, you need to install the R language and convenient packages +by running (as root): +

+
+
apt-get update ; sudo apt-get install r-base r-cran-knitr r-cran-ggplot2 
+
+
+ +

+Alternatively, if the installation of r-cran-gplot2 or r-cran-knitr +fails, you may want to install them locally (through the R packaging +system) and manually by running the following commands in R (or +Rstudio): +

+
+
install.packages("knitr")
+install.packages("ggplot2")
+
+
+ +

+If you plan to export pdf documents with LaTeX, you probably also want +to run (as root): +

+
+
apt-get update ; apt-get install texlive-base
+
+
+
+
+ +
+

Installing rstudio

+
+

+Rstudio is unfortunately not packaged within debian so the easiest is +to download the corresponding debian package on the Rstudio webpage +and then to install it manually (depending on when you do this, you +can obviously change the version number). Here is how to install it: +

+ +
+
cd /tmp/
+wget https://download1.rstudio.org/rstudio-xenial-1.1.453-amd64.deb
+sudo dpkg -i rstudio-xenial-1.1.453-amd64.deb
+sudo apt-get update ; sudo apt-get -f install # to fix possibly missing dependencies
+
+
+
+
+
+
+

Mac OSX and Windows

+
+
+

+Some instructions on installing R and knitr must be missing. This +should be tested and improved. +

+
+

+Download and install rstudio from the Rstudio webpage by choosing the +right operating system. +

+ +

+Then open Rstudio and type the following commands in the console to +install knitr and ggplot2: +

+
+
install.packages("knitr")
+install.packages("ggplot2")
+
+
+
+
+
+
+

Installing Git

+
+
+
+

Linux (debian, ubuntu)

+
+

+We provide here only instructions for debian-based distributions. Feel +free to contribute to this document to provide up-to-date information +for other distributions (e.g.n redhat, fedora). +

+ +

+Run (as root): +

+
+
apt-get update ; apt-get install git
+
+
+
+
+
+

Mac OSX and Windows

+
+ +
+
+
+
+

Rstudio and git/github/gitlab

+
+
+

+We may want to redo a screencast in French for this +

+
+ + +

+Alternatively, we can point to: +http://www.geo.uzh.ch/microsite/reproducible_research/post/rr-rstudio-git/ +

+
    +
  • Part 1/item 2: Setup Git in RStudio
    • +
  • Part 2 (to adapt to gitlab)
    • +
  • Part 3
    • +
+
+
+
+

Cheat Sheets

+
+

+The Rstudio team has created a lot of good material and tutorials. You +should definitively look at the Cheat sheets webpage. In particular +you want to have look at the ones on: +

+ + +

+In case it helps, here are some (sometimes outdated) French versions +of these documents: +

+ +
+
+
+
+

Date: June, 2018

+

Author: Arnaud Legrand

+

Created: 2018-07-19 jeu. 14:26

+

Validate

+
+ + -- 2.18.1