From b5411fd44e9010e1292ffced84b3b303be54e3b5 Mon Sep 17 00:00:00 2001 From: Arnaud Legrand Date: Fri, 21 Sep 2018 17:52:49 +0200 Subject: [PATCH] Regenerate HTML versions (should be propagated in FUN) --- module2/ressources/emacs_orgmode.html | 203 +++++++++-------- module2/ressources/gitlab.html | 112 ++++----- module2/ressources/jupyter.html | 316 ++++++++++++++++++-------- module2/ressources/rstudio.html | 96 ++++---- 4 files changed, 433 insertions(+), 294 deletions(-) diff --git a/module2/ressources/emacs_orgmode.html b/module2/ressources/emacs_orgmode.html index 00633bb..d341031 100644 --- a/module2/ressources/emacs_orgmode.html +++ b/module2/ressources/emacs_orgmode.html @@ -4,46 +4,46 @@

Table of Contents

@@ -64,13 +64,13 @@ the -

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

-
+
+

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

+
-
-

Linux (Debian, Ubuntu)

-
+
+

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 @@ -132,11 +132,11 @@ which is now deprecated.

-
-

macOS

-
+
+

macOS

+

-Note: macOS comes with a prehistoric command-line-only version of Emacs located at /usr/bin/emacs. It's best to forget about it. +Note: macOS comes with a prehistoric command-line-only version of Emacs located at /usr/bin/emacs. It's best to forget about it.

    @@ -189,9 +189,9 @@ in order to make Emacs accessible directly from /Applications.
-
-

Windows

-
+
+

Windows

+

Install the .exe file from Vincent Goulet: https://vigou3.github.io/emacs-modified-windows/. It ships with recent @@ -202,10 +202,19 @@ versions:

  • Org-mode 9.1.13
  • ESS 17.11
    • +

    +To have code pretty printing when exporting to html, it appears like +you should install the htmlize package, which is done by opening emacs +and typing the following command: +

    +
    +M-x package-install RET htmlize RET    # where M-x means pressing the "Esc" key then the "x" key
+
    -
    -

    Directory naming conventions

    -
    + +
    +

    Directory naming conventions

    +

    In all the following instructions, it is common to refer to your home directory through the (UNIX) ~/ notation. On Windows, your home @@ -216,9 +225,9 @@ means we are referring to C:\Users\yourname\org (resp.

    -
    -

    Making R and Python available to the console

    -
    +
    +

    Making R and Python available to the console

    +

    When running a command, windows will look for the command in the directories indicated in the PATH environment variable. If none of @@ -236,9 +245,9 @@ explained -

    Installing and configuring Matplotlib (graphic python library)

    -
    +
    +

    Installing and configuring Matplotlib (graphic python library)

    +

    Open an DOS console and type the following command:

    @@ -275,9 +284,9 @@ starting with backend, which amounts to use the default Agg
    -
    -

    A simple "reproducible research" emacs configuration

    -
    +
    +

    A simple "reproducible research" emacs configuration

    +

    This section is illustrated in a video tutorial ("Mise en place Emacs/Orgmode" in French). Watching it before following the @@ -296,9 +305,9 @@ adding a few org-mode specific configurations.

    -
    -

    Step 0: Backup and download our configuration

    -
    +
    +

    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 @@ -319,9 +328,9 @@ rr_org/journal.org

    -
    -

    Step 1: Prepare your journal

    -
    +
    +

    Step 1: Prepare your journal

    +

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

    @@ -338,9 +347,9 @@ should give a try.

    -
    -

    Step 2: Set up Emacs configuration

    -
    +
    +

    Step 2: Set up Emacs configuration

    +

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

    @@ -352,9 +361,9 @@ configuration with the following command: emacs -q -l rr_org/init.el
    -
    -

    Step 3: Adapt the configuration to your specific needs if required

    -
    +
    +

    Step 3: Adapt the configuration to your specific needs if required

    +

    There are two situations in which it might be necessary to modify init.el: @@ -383,9 +392,9 @@ beginning of the file for instructions.

    -
    -

    Step 4: Check whether the installation is working or not

    -
    +
    +

    Step 4: 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: @@ -416,9 +425,9 @@ is demonstrated in the -

    Step 5: Open and play with your journal:

    -
    +
    +

    Step 5: 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 @@ -429,9 +438,9 @@ FUN forums.

    -
    -

    A stub of replicable article

    -
    +
    +

    A stub of replicable article

    +

    This section is illustrated in a video tutorial ("Écrire un article réplicable avec Emacs/Orgmode" in French). Watching it before @@ -495,22 +504,22 @@ chunk of code when exporting.

    -
    -

    Emacs Tips and tricks

    -
    +
    +

    Emacs Tips and tricks

    +
    -
    -

    Cheat-sheets

    -
    +
    +

    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:

    -
    -

    Emacs

    -
    +
    +

    Emacs

    +
    -
    -

    Org-mode

    -
    +
    +

    Org-mode

    +
    -
    -

    Video tutorials

    -
    +
    +

    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

    -
    +
    +

    Additional useful emacs packages

    +
    -
    -

    Company-mode

    -
    +
    +

    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 @@ -554,9 +563,9 @@ official Web page: http://company-mode.

    -
    -

    Magit

    -
    +
    +

    Magit

    +

    Magit is an emacs interface for Git. Its usage is briefly illustrated in the context of this MOOC in a video tutorial ("Utilisation @@ -574,9 +583,9 @@ invoke magit by using C-x g.

    -
    -

    Other resources

    -
    +
    +

    Other resources

    +
    @@ -61,13 +61,13 @@ Please read all these instructions carefully, in particular the one on "Configuring your password on GitLab".

    -
    -

    Installing Git

    -
    +
    +

    Installing Git

    +
    -
    -

    Linux (debian, ubuntu)

    -
    +
    +

    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 @@ -83,9 +83,9 @@ Run (as root):

    -
    -

    Mac OSX and Windows

    -
    +
    +

    Mac OSX and Windows

    +
    • Download and install Git from the Git website.
    • Optional Git clients (should not be needed if you work within @@ -105,13 +105,13 @@ Rstudio):
    -
    -

    Configuring Git

    -
    +
    +

    Configuring Git

    +
    -
    -

    Telling Git who you are: Name and Email

    -
    +
    +

    Telling Git who you are: Name and Email

    +
    1. Open Terminal.

    2. @@ -140,9 +140,9 @@ email@example.com

    -
    -

    Dealing with proxies

    -
    +
    +

    Dealing with proxies

    +

    You may be behind a proxy, in which case you may have trouble cloning or fetching from a remote repository or you may get an error like @@ -164,9 +164,9 @@ will be prompted for it every time it is needed.

    -
    -

    Getting your default password on GitLab (and possibly changing it)

    -
    +
    +

    Getting your default password on GitLab (and possibly changing it)

    +

    Warning (Jupyter users) : changing your default Gitlab password will prevent you from committing in Jupyter. You will have to do the extra step of changing your Jupyter ~/.git-credentials

    @@ -224,8 +224,8 @@ button).

  • -If you wish to modify your password, you shoul go to Account > - Settings > Password and define your password using the default +If you wish to modify your password, you shoul go to Account > Settings > Password +and define your password using the default password you just retrieved. Again, if you use the Jupyter notebooks we have deployed for the MOOC, remember that changing your default Gitlab password will prevent you from committing in @@ -242,9 +242,9 @@ section).

    • -
    -

    Remembering your password locally

    -
    +
    +

    Remembering your password locally

    +

    If you clone your repository by simply pasting the GitLab URL, you will be prompted for your login and your password every time you want to @@ -278,9 +278,9 @@ Use it at your own risk.

    -
    -

    Optional: authenticating through SSH

    -
    +
    +

    Optional: authenticating through SSH

    +

    There are two ways of authenticating and synchronizing your local repository with GitLab: through HTTPS or through SSH. The first one is @@ -293,13 +293,13 @@ your SSH public key on GitLab. This section provides with information on how to do this.

    -
    -

    Installing SSH

    -
    +
    +

    Installing SSH

    +
      -
    • Linux (debian, ubuntu)
      -
      +
    • 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 @@ -315,15 +315,15 @@ Run (as root):

    -
  • Mac OSX
    -
    +
  • Mac OSX
    +

    You do not have anything to do as it is installed by default.

    • -
  • Windows
    -
    +
  • Windows
    +

    You should install the Putty client. Once it is installed, look for the section on generating an SSH key. @@ -332,9 +332,9 @@ the section on generati

    • -
    -

    Setting up SSH on GitLab

    -
    +
    +

    Setting up SSH on GitLab

    +

    Here are all the official explanations on how to set up your SSH key on GitLab. Alternatively, you may also want to have a look at this @@ -345,9 +345,9 @@ video:

    -
    -

    Using Git through the command line to synchronize your local files with Gitlab

    -
    +
    +

    Using Git through the command line to synchronize your local files with Gitlab

    +

    This section describes a generic (through the command line) way to synchronize your local files with Gitlab. You will not need this if diff --git a/module2/ressources/jupyter.html b/module2/ressources/jupyter.html index e6040b4..7c2741c 100644 --- a/module2/ressources/jupyter.html +++ b/module2/ressources/jupyter.html @@ -4,22 +4,28 @@

    Table of Contents

    -
    -

    Additional Jupyter resources or tricks

    -
    -
    -
    -

    Tips and tricks

    -
    +
    +

    1. Jupyter Tips and tricks

    +

    The following webpage lists several Jupyter tricks (in particular, it illustrates many Ipython magic commands) that should improve your @@ -43,28 +45,11 @@ 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. E.g., -

    -
    -
    sudo apt-get install python3-rpy2 python3-tzlocal
-
    -
    -

    -An other (not really recommended if the first one is available) -alternative consists in going through the python package manager with -

    -
    -
    pip3 install rpy2
-
    -
    +
    +

    Running R and Python in the same notebook

    +

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

    1. @@ -93,51 +78,57 @@ plot(df)

    -Note that this %%R notation allows you to use R for the whole cell but +Note that this %%R notation indicates that R should be used for the whole cell but an other possibility is to use %R to have a single line of R within a python cell.

    -
    -

    Exporting a notebook

    -
    +
    +

    Other languages

    +

    -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: +For any reason, you may be unsatisfied with the use of R or of +Python. Many other languages are available: +https://github.com/jupyter/jupyter/wiki/Jupyter-kernels, including +non-free languages like SAS, Mathematica, Matlab…

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

    +None of these other languages have been deployed in the context of our +MOOC but you may want to read the next sections to know more about how +to set up your own Jupyter notebooks on your computer and benefit from these +extensions. +

    - +
    +
    +
    +

    2. Installing and configuring Jupyter on your computer

    +

    -If you want to use a specific style, then the nbconvert exporter -should be customized. This is discussed and demoed here. We encourage -you to simply read the doc of nbconvert. +In this Section, we provide information on how to set up on your own +computer a Jupyter environment similar to the one deployed for this +MOOC.

    -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. +Note that Jupyter notebooks are only a small part of the picture and +that Jupyter is now part of a bigger project: JupyterLab, which allows +you to mix various components (including notebooks) in your +browser. In the context of this MOOC, our time frame was too short to +benefit from JupyterLab which was still under active development but +this is probably the best option now if you want to benefit from +cutting-edge Jupyter notebooks.

    -
    -
    -
    -

    Installing Jupyter on your own machine

    -
    -
    -
    -

    Installing Jupyter

    -
    + +
    +

    2.1 Installing Jupyter

    +

    Follow these instructions if you wish to have a Jupyter environment on -your own machine similar to the one we set up for this MOOC. +your own computer similar to the one we set up for this MOOC.

    @@ -161,46 +152,161 @@ activate mooc_rr # Linux and MacOS activate the environment source activate mooc_rr +# Linux, MacOS and Windows: launch the notebook jupyter notebook

    -
    -

    Side note about Jupyter, JupyterLab, JupyterHub, …

    -
    +
    +

    2.2 Making sure Jupyter allows you to use R

    +

    -Note that Jupyter notebooks are only a small part of the picture and -that Jupyter is now part of a bigger project: JupyterLab, which allows -you to mix various components (including notebooks) in your -browser. In the context of this MOOC, our time frame was too short to -benefit from JupyterLab which was still under active development but -this is probably the best option now if you want to benefit from -cutting-edge Jupyter notebooks. +The previous environment should ship with R but if you proceeded +otherwise and only have python available in Jupyter, you may want to +read the following section. +

    +
    +
    +

    • Installing IRKernel (R package)

    +
    +

    +Do the following in R console: +

    + +

    +Install the devtools package: +

    + +
    +
    install.packages('devtools',dep=TRUE)
+
    +
    + +

    +Define a proxy if needed: +

    + +
    +
    library(httr)
+set_config(use_proxy(url="proxy", port=80, username="username", password="password")) 
+
    +
    + +

    +Install the IRkernel package: +

    + +
    +
    devtools::install_github('IRkernel/IRkernel')
+IRkernel::installspec()  # to register the kernel in the current R installation
+
    +
    +
    +
    + +
    +

    • Installing rpy2 (Python package)

    +
    +

    +On Linux, the rpy2 package is available in standard distributions

    +
    +
    sudo apt-get install python3-rpy2 python3-tzlocal
+
    +

    +An other (not really recommended if the first one is available) +alternative consists in going through the python package manager with +

    +
    +
    pip3 install rpy2
+
    -
    -

    Exporting your notebooks with latex

    -
    +

    -Here is what we had to install on our recent debian machine to make sure -the notebook export via latex works: +Windows +

    + +

    +Download rpy2 binary file by choosing the right operating system. +

    + +

    +Open a DOS console and type the following command: +

    +
    +
    python -m pip install rpy2‑2.9.4‑cp37‑cp37m‑win_amd64.whl # adapt filename
+
    +
    + +

    +Install also tzlocal: +

    +
    +
    python -m pip install tzlocal
+
    +
    +
    +
    +
    +
    +

    2.3 Additional tips

    +
    +
    +
    +

    • Exporting a notebook

    +
    +

    +Here is what we had to install on our recent debian computer to make sure +the notebook export via LaTeX works: 

    sudo apt-get install texlive-xetex wkhtmltopdf
    + +

    +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 customized. 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. +

    + +

    +Windows +

    + +

    +Download and install MiKTeX from the MiKTeX webpage +by choosing the right operating system. You will be prompted to install some specific +packages when exporting to pdf. +

    -
    -

    Jupyter extensions/plugins

    -
    +
    +

    • Side note about Jupyter, JupyterLab, JupyterHub…

    -
    -

    Improving notebook readability

    -
    +
    +

    • Improving notebook readability

    +

    Here are a few extensions that can ease your life:

    @@ -226,9 +332,10 @@ jupyter-serverextension enable --py hide_code
    -
    -

    Interacting with GitLab and GitHub

    -
    + +
    +

    • Interacting with GitLab and GitHub

    +

    To ease your experience, we added some pull/push buttons that allow you to commit and sync with GitLab. This development was specific to @@ -259,6 +366,33 @@ developed to offer a nice version control experience.

    + +
    +

    • Using other languages (e.g., SAS, Matlab, Mathematica, etc.)

    +
    +

    +For any reason, you may be unsatisfied with the use of R or of +Python. Many other languages are available: +https://github.com/jupyter/jupyter/wiki/Jupyter-kernels, including +non-free languages like SAS, Mathematica, Matlab… +

    + +

    +Since the question was asked several times, if you really need to stay +with SAS, you should know that SAS can be used within Jupyter using +either the Python SASKernel or the Python SASPy package (step by step +explanations about this are given here). +

    + +

    +Since such software cannot easily be opened for inspection not widely +used, we discourage this approach as it hinders reproducibility by +essence. But perfection does not exist anyway and using Jupyter +literate programming approach allied with systematic control version +and environment control will certainly help anyway. +

    +
    +
    diff --git a/module2/ressources/rstudio.html b/module2/ressources/rstudio.html index c68386e..97f9b77 100644 --- a/module2/ressources/rstudio.html +++ b/module2/ressources/rstudio.html @@ -4,21 +4,21 @@

    Table of Contents

    @@ -66,13 +66,13 @@ of these documents:
  • Un court document sur R Markdown
    • -
    -

    Installing Rstudio

    -
    +
    +

    Installing Rstudio

    +
    -
    -

    Linux (debian, ubuntu)

    -
    +
    +

    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 @@ -94,9 +94,9 @@ for upgrading…

    -
    -

    Installing R

    -
    +
    +

    Installing R

    +

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

    -
    -

    Installing rstudio

    -
    +
    +

    Installing rstudio

    +

    Rstudio is unfortunately not packaged within debian so the easiest is to download the corresponding debian package on the Rstudio webpage @@ -149,46 +149,42 @@ sudo apt-get update ; sudo apt-get -f install -

    Mac OSX and Windows

    -
    +
    +

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

    +
      +
    • Download and install R from the CRAN webpage by choosing the right operating system.
      • +
    • Download and install Rstudio from the Rstudio webpage by choosing the right operating system.
      • +
    • Download and install MiKTeX from the MiKTeX webpage by choosing the right operating system. You will be prompted to install some specific packages when exporting to pdf.
      • +
    • Open Rstudio and type the following commands in the console to install knitr and ggplot2:
      • +
    -
    install.packages("knitr")
-install.packages("ggplot2")
+
    install.packages("knitr", dep=TRUE)
+install.packages("ggplot2", dep=TRUE)
    -
    -

    Using Git from Rstudio

    -
    +
    +

    Using Git from Rstudio

    +
    -
    -

    Cloning a repository

    -
    +
    +

    Cloning a repository

    +

    Open RStudio and do the following steps:

    • -Create a new version controled project: File / New Project / Version - Control +Create a new version controled project: File / New Project / Version Control

      @@ -198,7 +194,7 @@ Create a new version controled project: File / New Project / Version
      -

      git.png

      +

      git.png

    • @@ -207,7 +203,7 @@ Get the url from your gitlab repository:

      -

      adresse_depot.png

      +

      adresse_depot.png

    • @@ -218,7 +214,7 @@ repeatedly giving it later on).

      -

      clone.png

      +

      clone.png

    • If you're behind a proxy, git should be configured @@ -231,7 +227,7 @@ RStudio should restart in a mode related to Git:
      -

      rstudio.png

      +

      rstudio.png

    • The file manager on the right, allows you to browse the version @@ -239,9 +235,9 @@ controled repository.
    -
    -

    Modifying a file

    -
    +
    +

    Modifying a file

    +
    • Open Module2/exo1/toy_document.Rmd and perform a simple modification.
      • @@ -266,7 +262,7 @@ Select the lines to commit and then click on commit
      -

      commit5.png

      +

      commit5.png

      -- 2.18.1