Jupyter en R Markdown: notebooks met R

R en de Jupyter Notebook

In tegenstelling tot wat je misschien denkt, beperkt Jupyter je niet tot alleen Python: de notebooktoepassing is taalagnostisch, wat betekent dat je ook met andere talen kunt werken. 

Er zijn grofweg twee manieren om met R in Jupyter te starten: door een kernel te gebruiken of door een R-omgeving op te zetten met alle essentiële tools om met data science te beginnen.

R draaien in Jupyter met de R-kernel

Zoals hierboven beschreven, is de eerste manier om R te draaien via een kernel. Voor een volledige lijst van alle beschikbare kernels in Jupyter, ga hierheen.

Om met R te werken, moet je de IRKernel laden en activeren om aan de slag te gaan met R in de notebookomgeving.

Eerst moet je een paar packages installeren. Zorg dat je dit niet in je RStudio-console doet, maar in een reguliere R-terminal, anders krijg je een fout zoals deze:

Error in IRkernel::installspec() :
Jupyter or IPython 3.0 has to be installed but could neither run “jupyter” nor “ipython”, “ipython2” or “ipython3”.
(Note that “ipython2” is just IPython for Python 2, but still may be IPython 3.0)

$ R

> install.packages(c('repr', 'IRdisplay', 'evaluate', 'crayon', 'pbdZMQ', 'devtools', 'uuid', 'digest'))

Dit commando vraagt je om een nummer te typen om een CRAN-mirror te selecteren om de benodigde packages te installeren. Voer een nummer in en de installatie gaat verder.

> devtools::install_github('IRkernel/IRkernel')

Vervolgens moet je de R-kernel nog zichtbaar maken voor Jupyter:

# Install IRKernel for the current user

> IRkernel::installspec()

# Or install IRKernel system-wide

> IRkernel::installspec(user = FALSE)

Open nu de notebooktoepassing met jupyter notebook. Je ziet R verschijnen in de lijst met kernels wanneer je een nieuw notebook maakt. 

Een R Essentials-omgeving gebruiken in Jupyter

De tweede optie om snel met R te werken is om de R essentials in je huidige omgeving te installeren:

conda install -c r r-essentials

Deze "essentials" bevatten de packages dplyr, shiny, ggplot2, tidyr, caret en nnet. Als je de essentials niet in je huidige omgeving wilt installeren, kun je met het volgende commando een nieuwe omgeving maken alleen voor de R essentials:

conda create -n my-r-env -c r r-essentials

Open nu de notebooktoepassing om met R te gaan werken.

Je vraagt je misschien af wat je moet doen als je extra packages wilt installeren om je data-scienceproject uit te breiden. Deze packages zijn genoeg om te starten, maar je hebt mogelijk andere tools nodig.

Je kunt ofwel een Conda R-package bouwen door bijvoorbeeld het volgende uit te voeren:

conda skeleton cran ldavis conda build r-ldavis/

Of je installeert het package vanuit R zelf via install.packages() of devtools::install_github (om packages van GitHub te installeren). Zorg er alleen voor dat je het nieuwe package toevoegt aan de juiste R-bibliotheek die door Jupyter wordt gebruikt:

install.packages("ldavis", "/home/user/anaconda3/lib/R/library")

Als je meer wilt weten over kernels of over R draaien in een Docker-omgeving, bekijk dan deze pagina.

Een beetje R-magic toevoegen aan Jupyter

Een groot voordeel van werken met notebooks is dat ze je een interactieve omgeving bieden. Die interactiviteit komt vooral van de zogenaamde "magic commands".

Met deze commando's kun je schakelen van Python naar commandline-instructies of code schrijven in een andere taal zoals R, Julia, Scala, …

Om te schakelen van Python naar R, moet je eerst het volgende package downloaden:

%load_ext rpy2.ipython

Daarna kun je met R aan de slag, of eenvoudig in je data-analyse van Python naar R wisselen met het %R-magiccommando.

We demonstreren hoe de R-magic werkt met een klein voorbeeld:

# Hide warnings if there are any
import warnings
warnings.filterwarnings('ignore')
# Load in the r magic
%load_ext rpy2.ipython
# We need ggplot2
%R require(ggplot2)
# Load in the pandas library
import pandas as pd 
# Make a pandas DataFrame
df = pd.DataFrame({'Alphabet': ['a', 'b', 'c', 'd','e', 'f', 'g', 'h','i'],
                   'A': [4, 3, 5, 2, 1, 7, 7, 5, 9],
                   'B': [0, 4, 3, 6, 7, 10,11, 9, 13],
                   'C': [1, 2, 3, 1, 2, 3, 1, 2, 3]})
# Take the name of input variable df and assign it to an R variable of the same name
%%R -i df
# Plot the DataFrame df
ggplot(data=df) + geom_point(aes(x=A, y=B, color=C))

Wil je meer details over Jupyter, hoe je een notebook opzet, waar je de toepassing downloadt, hoe je de notebooktoepassing draait (via Docker, pip install of met de Anaconda-distributie) of andere details, bekijk dan onze Definitive Guide.

De R Notebook

Tot voor kort leek Jupyter een populaire oplossing voor R-gebruikers, naast notebooks zoals Apache Zeppelin of Beaker.

Ook andere alternatieven om resultaten van data-analyses te rapporteren, zoals R Markdown, Knitr of Sweave, zijn erg populair geweest in de R-community.

Dit kan echter veranderen met de recente release van de R- of R Markdown Notebook door RStudio.

Je ziet het: de context van de R Markdown Notebook is complex, en het is de moeite waard om in de geschiedenis van reproduceerbaar onderzoek in R te duiken om te begrijpen wat de creatie en ontwikkeling van deze notebook heeft gedreven. Uiteindelijk zul je ook beseffen dat deze notebook anders is dan andere. 

R en de geschiedenis van reproduceerbaar onderzoek

In zijn talk bevestigt J.J. Allaire dat de inspanningen in R zelf voor reproduceerbaar onderzoek, de inspanningen van Emacs om tekst, code en input te combineren, de projecten Pandoc, Markdown en knitr, en computationele notebooks jarenlang parallel zijn geëvolueerd en elkaar hebben beïnvloed. Hij bevestigt dat al deze factoren uiteindelijk hebben geleid tot de creatie en ontwikkeling van notebooks voor R.

Ten eerste hebben computationele notebooks behoorlijk wat geschiedenis: sinds de late jaren 80, toen de front-end van Mathematica werd uitgebracht, zijn er veel ontwikkelingen geweest. In 2001 begon Fernando Pérez met de ontwikkeling van IPython, maar pas in 2011 werd versie 0.12 van IPython uitgebracht. Het SageMath-project begon in 2004. Daarna kwamen er veel notebooks. De meest opmerkelijke voor de data-sciencegemeenschap zijn Beaker (2013), Jupyter (2014) en Apache Zeppelin (2015). 

Dan zijn er ook de opmaak­talen en teksteditors die de creatie van RStudio’s notebooktoepassing hebben beïnvloed, namelijk Emacs, Markdown en Pandoc. Org-mode werd in 2003 uitgebracht. Het is een bewerk- en organiseermodus voor notities, planning en auteurschap in de vrije softwareteksteditor Emacs. Zes jaar later kwam Emacs org-R om ondersteuning te bieden voor R-gebruikers. Markdown daarentegen werd in 2004 uitgebracht als een opmaaktaal waarmee je platte tekst zo kunt formatteren dat deze kan worden omgezet naar HTML of andere formaten. Een paar jaar vooruit, en Pandoc werd uitgebracht. Het is een schrijftool en basis voor publicatieworkflows.

Tot slot hebben de inspanningen van de R-community om onderzoek reproduceerbaar en transparant te maken ook bijgedragen aan de opkomst van een notebook voor R. In 2002 werd Sweave geïntroduceerd om R-code in LaTeX-documenten te kunnen insluiten om PDF-bestanden te genereren. Deze pdf-bestanden combineerden het verhaal en de analyse, grafieken, code en de resultaten van berekeningen. Tien jaar later werd knitr ontwikkeld om langlopende problemen in Sweave op te lossen en functies die aanwezig waren in andere add-on-packages te combineren in één package. Het is een transparante engine voor dynamische rapportgeneratie in R. Knitr staat elke invoertaal en elke uitvoeropmaaktaal toe.

Ook in 2012 werd R Markdown gemaakt als een variant van Markdown die R-codechunks kan insluiten en die met knitr kan worden gebruikt om reproduceerbare webgebaseerde rapporten te maken. Het grote voordeel was en is nog steeds dat LaTeX niet meer nodig is, wat een leercurve heeft om te leren en te gebruiken. De syntaxis van R Markdown lijkt sterk op de reguliere Markdown-syntaxis maar heeft enkele aanpassingen, omdat je bijvoorbeeld LaTeX-vergelijkingen kunt opnemen.

R Markdown versus computationele notebooks

R Markdown is waarschijnlijk een van de populairste opties in de R-community om over data-analyses te rapporteren. Het is dan ook geen verrassing dat het nog steeds een kernonderdeel is van de R Markdown Notebook. 

Er zijn dingen die R Markdown en notebooks delen, zoals het leveren van een reproduceerbare workflow, het verweven van code, output en tekst in één document, ondersteuning voor interactieve widgets en uitvoer naar meerdere formaten. Ze verschillen echter in hun accenten: R Markdown focust op reproduceerbare batchuitvoering, platte-tekstrepresentatie, versiebeheer, productie-uitvoer en biedt dezelfde editor en tools die je voor R-scripts gebruikt.

Traditionele computationele notebooks focussen daarentegen op inline uitvoer bij de code, het cachen van output over sessies heen, het delen van code en output in één bestand. Notebooks leggen de nadruk op een interactief uitvoeringsmodel. Ze gebruiken geen platte-tekstrepresentatie, maar een gestructureerde datarepresentatie, zoals JSON.

Dat verklaart het doel van RStudio’s notebooktoepassing: die combineert alle voordelen van R Markdown met de goede dingen die computationele notebooks te bieden hebben.

Daarom is R Markdown een kernonderdeel van de R Markdown Notebook: RStudio definieert zijn notebook als "een R Markdown-document met chunks die onafhankelijk en interactief kunnen worden uitgevoerd, met output direct zichtbaar onder de input".

Werken met R Notebooks

Als je ooit met Jupyter of een andere computationele notebook hebt gewerkt, zie je dat de workflow erg vergelijkbaar is. Eén ding dat anders kan lijken, is dat je nu standaard niet meer met codecellen werkt: je werkt eerder met een soort teksteditor waarin je je codechunks aangeeft met R Markdown.

De R Markdown Notebook installeren en gebruiken

De eerste vereiste om de notebook te gebruiken is dat je de nieuwste versie van RStudio op je pc hebt. Omdat notebooks een nieuwe functie van RStudio zijn, zijn ze alleen beschikbaar in versie 1.0 of hoger van RStudio. Het is dus belangrijk om te controleren of je een juiste versie hebt geïnstalleerd.

Als je geen versie 1.0 of hoger van RStudio hebt, kun je de nieuwste versie hier downloaden.

Om een nieuwe notebook te maken, ga je naar het tabblad File, selecteer je "New File", en je ziet de optie om een nieuwe R Markdown Notebook te maken. Als RStudio je vraagt om enkele packages te updaten, accepteer dat, en uiteindelijk verschijnt er een nieuw bestand.

Tip: controleer dubbel of je met een notebook werkt door bovenaan je document te kijken. De output zou html_notebook moeten zijn.

Je ziet dat de standaardtekst die in het document verschijnt in R Markdown is. R Markdown zou je behoorlijk bekend moeten voorkomen, maar als je nog niet zo vaardig bent, kun je altijd onze Reporting With R Markdown-cursus bekijken of het materiaal van RStudio doornemen.

Let op dat je altijd via het tandwielpictogram de werkruimte van de notebook kunt aanpassen: je kunt de output van je code uitklappen, inklappen en verwijderen, de voorbeeldopties wijzigen en de outputopties aanpassen.

Die laatste optie is handig als je de syntax highlighting wilt aanpassen, een ander thema wilt toepassen, de standaardbreedte en -hoogte van figuren in je output wilt instellen, enz.

Vanaf daar kun je codechunks en tekst gaan invoegen!

Je kunt codechunks op twee manieren toevoegen: via de sneltoets Ctrl + Alt + I of Cmd + Option + I,  of met de Insert-knop in de toolbar. 

Wat geweldig is aan werken met deze R Markdown-notebooks, is dat je de uitvoering van je codechunks kunt volgen dankzij de kleine groene balk links die verschijnt wanneer je grote codechunks of meerdere chunks tegelijk uitvoert. Let ook op de voortgangsbalk onderaan.

Je ziet de groene voortgangsbalk verschijnen in de gif hieronder:

Over code-uitvoering gesproken: er zijn meerdere manieren waarop je je R-codechunks kunt uitvoeren.

Je kunt een codechunk draaien of de volgende chunk uitvoeren, alle chunks hieronder en hierboven uitvoeren; maar je kunt ook kiezen om R te herstarten en alle chunks te draaien of te herstarten en de output te wissen.

Let op dat wanneer je de code van de notebook uitvoert, de output ook in je console verschijnt! Dat kan een groot verschil zijn voor wie meestal met andere computationele notebooks zoals Jupyter werkt.

Als er fouten optreden tijdens het uitvoeren van de codechunks van de notebook, stopt de uitvoering, en verschijnt er een rode balk naast het codegedeelte dat de fout veroorzaakt.

Je kunt het stoppen van de uitvoering onderdrukken door errors = TRUE toe te voegen aan de chunkopties, zo:

```{r, error=TRUE}
iris <- read.csv(url("http://mlr.cs.umass.edu/ml/machine-leaning-databases"), header = FALSE)
names(iris) <- c("Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width", "Species")
```

Let op dat de fout nog steeds verschijnt, maar dat de code-uitvoering van de notebook niet wordt onderbroken!

De magic van de R Markdown Notebook gebruiken

Net als bij Jupyter kun je ook interactief werken met je R Markdown-notebooks. Het werkt een beetje anders dan Jupyter, omdat er geen echte magic-commando’s zijn; Om met andere talen te werken, moet je aparte Bash-, Stan-, Python-, SQL- of Rcpp-chunks aan de notebook toevoegen. 

Deze opties lijken misschien wat beperkt, maar dat wordt gecompenseerd door het gemak waarmee je deze soorten codechunks eenvoudig toevoegt met de Insert-knop van de toolbar.

Ook werken met deze codechunks is eenvoudig: je ziet een voorbeeld van SQL-chunks in dit document, gepubliceerd door J.J. Allaire. Voor Bash-commando’s typ je gewoon het commando. Extra tekens zoals ‘!’ om aan te geven dat je in Bash werkt, zijn niet nodig, zoals je bij Jupyter wel zou doen. 

Je R Markdown-notebooks exporteren 

Voordat je de definitieve versie van een notebook rendert, wil je misschien een preview zien van wat je hebt gedaan. Daar is een handige functie voor: je vindt die in je toolbar. 

Klik op de knop "preview" en de voorlopige versie van je document verschijnt aan de rechterkant, in het tabblad "Viewer".

Door bovenaan de notebook enkele regels toe te voegen, kun je je outputopties aanpassen, zoals dit:

---
title: "Notebook with KNN Example"
output:
  pdf_document:
    highlight: tango
    toc: yes
  html_notebook:
    toc: yes
---

Om te zien waar je die distributies kunt krijgen, kun je gewoon proberen te knitten, en de console-output geeft de sites waar je de benodigde packages kunt downloaden. 

Let op: dit is slechts een van de vele opties om een notebook te exporteren: er is ook de mogelijkheid om GitHub-documenten, Word-documenten, beamerpresentaties, enz. te renderen. Dit zijn de outputopties die je al had met reguliere R Markdown-bestanden. Je vindt meer info hier. 

Tips en tricks voor werken met R Notebook

Naast de algemene codeerpraktijken die je in gedachten moet houden, zoals je code documenteren en een consistent naamgevingsschema, codegroepering en naamlengte toepassen, kun je ook de volgende tips gebruiken om een notebook fijn leesbaar en bruikbaar te maken voor anderen:

• Net als bij computationele notebooks kan het handig zijn om grote codechunks of chunks die meer dan één output genereren op te splitsen in meerdere chunks. Zo verbeter je de algemene gebruikerservaring en vergroot je de transparantie van een notebook.
• Maak gebruik van de sneltoetsen om je werk te versnellen. Je vindt de meeste in de toolbar, naast de acties die je wilt uitvoeren. 
• Gebruik de spellingcontrole in de toolbar om zeker te zijn dat de woordkeuze in je rapport klopt. 
• Maak gebruik van de optie om je code te verbergen als een notebook veel code bevat. Dit kan via chunkopties of in het HTML-bestand van de notebook zelf!

De R Notebook versus de Jupyter Notebook

Naast de verschillen tussen de Jupyter- en R Markdown-notebooks die je hierboven al hebt gelezen, zijn er nog een paar zaken.

Laten we Jupyter vergelijken met de R Markdown Notebook!

Er zijn vier aspecten die interessant zijn om te overwegen: het delen van notebooks, code-uitvoering, versiebeheer en projectmanagement.

Notebooks delen

De broncode voor een R Markdown-notebook is een .Rmd-bestand. Maar wanneer je een notebook opslaat, wordt er een .nb.html-bestand naast aangemaakt. Dit HTML-bestand is een gekoppeld bestand dat een kopie bevat van de R Markdown-broncode en de gegenereerde output. 

Dat betekent dat je geen speciale viewer nodig hebt om het bestand te zien, terwijl je die mogelijk wel nodig hebt om notebooks te bekijken die met de Jupyter-toepassing zijn gemaakt, die simpele JSON-documenten zijn, of andere computationele notebooks met gestructureerde bestandsindelingen. Je kunt je R Markdown-notebook publiceren op elke webserver, GitHub of als e-mailbijlage.

Er zijn ook API’s om R Markdown-notebooks te renderen en te parsen: dit geeft andere front-endtools de mogelijkheid om auteurmodi voor R Markdown-notebooks te maken. Of de API’s kunnen worden gebruikt om conversietools naar en van verschillende notebookformaten te maken.

Om de notebooks die je in de Jupyter-toepassing maakt te delen, kun je de notebooks exporteren als slideshows, blogs, dashboards, enz. Je vindt meer informatie in deze tutorial. Er zijn echter ook de standaardopties om Python-scripts, HTML-bestanden, Markdown-bestanden, PDF-bestanden of reStructured Text-bestanden te genereren.

Code-uitvoering

R Markdown-notebooks hebben opties om een codechunk te draaien of de volgende chunk uit te voeren, alle chunks hieronder en hierboven te draaien; Daarnaast kun je ook kiezen om R te herstarten en alle chunks te draaien of te herstarten en de output te wissen.

Deze opties zijn interessant wanneer je met R werkt, omdat de R Markdown Notebook alle R-code­stukken in dezelfde omgeving laat draaien. Dit kan echter een groot nadeel zijn als je met niet-R-code­stukken werkt, omdat die geen omgevingen delen.

Alles bij elkaar bieden deze uitvoeringsopties flink wat flexibiliteit voor gebruikers die worstelen met de uitvoeringsopties die Jupyter biedt, ook al verschillen die niet heel veel: in de Jupyter-toepassing kun je een enkele cel draaien, cellen uitvoeren en alle cellen uitvoeren. Je kunt ook kiezen om de huidige of alle outputs te wissen. De codeomgeving wordt gedeeld tussen codecellen.

Versiebeheer

Er is beweerd dat Jupyter het versiebeheer van notebooks in de war schopt of dat git lastig is met deze notebooks. Oplossingen zijn om de notebook als script te exporteren of een filter in te stellen om delen van de metadata te fixen die niet zouden moeten veranderen wanneer je commit, of om het run-nummer en de output te strippen.

De R Markdown-notebooks lijken dit probleem iets makkelijker te maken: doordat er gekoppelde HTML-bestanden zijn die de output van je code bewaren en doordat de notebookbestanden in essentie platte tekst zijn, wordt versiebeheer een stuk eenvoudiger. Je kunt ervoor kiezen om alleen je .Rmd-bestand op GitHub of je andere versiebeheersysteem te zetten, of je kunt ook het .nb.html -bestand toevoegen.

Projectmanagement

Omdat de R Markdown Notebook native is voor de RStudio-ontwikkelomgeving, integreren de notebooks naadloos met je R-projecten. Ook ondersteunen deze notebooks andere talen, waaronder Python, C en SQL.

Aan de andere kant is het Jupyter-project niet native voor een specifieke ontwikkelomgeving: in die zin kost het wat moeite om deze notebook naadloos te integreren met je projecten. Maar deze notebook ondersteunt wel meer talen en is geschikter als je bijvoorbeeld Scala, Apache Toree, Julia of een andere taal wilt gebruiken. 

Alternatieven voor Jupyter- of R Markdown-notebooks

Naast de notebooks die je kunt gebruiken als interactieve data-scienceomgevingen waarmee je je code gemakkelijk deelt met collega’s, peers en vrienden, zijn er ook andere alternatieven om te overwegen.

Want soms heb je geen notebook nodig, maar een dashboard, een interactief leerplatform of een boek, bijvoorbeeld.

Je hebt al gelezen over opties zoals Sweave en Knitr in de tweede sectie. Andere opties die er zijn, zijn:

• Hoewel deze blogpost R Markdown in zekere mate heeft behandeld, moet je weten dat je er nog veel meer mee kunt. Zo kun je dashboards bouwen met flexdashboard.
• Of je gebruikt Bookdown om snel HTML-, PDF-, ePub- en Kindle-boeken te publiceren met R Markdown. 
• Shiny is een tool die je ook kunt gebruiken om dashboards te maken. Ga naar deze pagina om met Shiny te starten.
• In een onderwijssetting kan DataCamp Light ook handig zijn om interactieve tutorials op je blog of website te maken. Als je DataCamp Light in actie wilt zien, ga dan bijvoorbeeld naar deze tutorial.