Communiceren met RMarkdown

RMarkdown is de nieuwe manier om diverse wetenschappelijke producten te delen met anderen. Het kan op verschillende manieren gereproduceerd worden en het kan de opbrengsten aantrekkelijk communiceren naar de buitenwereld. Hier een introductie op de werkwijze en enkele mogelijke producten.

M. Schmidt en bewerkt door Harrie Jonkman https://Harriejonkman.nl
11-26-2018

Van \(\Latex\) naar RMarkdown

Eerder schreef ik een snelle introductie op enkele algemene kenmerken van LaTeX, een opensource software syteem om verschillende soorten documenten te zetten. Dit programmma wordt vooral gebruikt voor maken van wetenschappelijke documenten. Die introductie is hier te vinden. Daarin laat ik zien hoe \(\Latex\) werkt en welke verschillende soorten documenten je ermee kunt maken (waaronder artikel, boek, rapport, een poster, een proefschrift, een presentatie). Verder kun je hier \(\Latex\)-tutorial ook informatie vinden en hier Snel overzicht.

\(\Latex\) werkt met veel verschillende commando’s en je moet de tijd nemen dit te leren. Op internet is overigens wel goede informatie te vinden en de meeste problemen kun je zelf oplossen. De laatste jaren vinden er binnen het programma R veel ontwikkelingen plaats die het maken van wetenschappelijke documenten vergemakkelijken. De ontwikkelingen vallen onder de term RMarkdown dat in 2015 met de introductie van het knitr-pakket werd geïntroduceerd. Hier wordt binne R gebruik gemaakt van de Markdown taal waarmee technische documenten betrekkelijk eenvoudig te maken zijn. Het pakket maakt het mogelijk om verschillende soorten documenten te maken (waaronder pdf, html en word). Tot slot maakt RMarkdown het mogelijk om tekst (inclusief bv. grafieken, tabellen en referentie) en analyses in een keer te draaien. Met RMarkdown, knitr en alles wat hier aan vastzit kun je onder anderen:
- Een goed uitziend wetenschappelijk document maken in verschillende formats tegelijkertijd (pdf, html en word);
- Kun je met notebooks werken waarin naast tekst analyses zijn opgenomen;
- Kun je nieuwe vormen van presentaties voorbereiden;
- Kun je dashboards maken waarin informatie overzichtelijk, aantrekkelijk, flexibel en interactief wordt gepresenteerd;
- Kun je interactieve toepassingen maken bijvoorbeeld door de inzet van Shiny; - Kun je wetenschappelijke artikelen maken; - Kun je boeken zelf maken; - KUn je een blog en website maken.

Een uitgebreide gids hierover vind je hier RMarkdown: The Definitive Guide. En een handleiding vind je hier Cheat sheet RMarkdown.

Installatie

Om met onderstaande te kunnen werken moet je in ieder geval R installeren R alsmede RStudio RStudio. Om pdf te draaien moet je ook Latex op je computer installeren. Heb je dat niet kun je ook binnen R/RStudio het pakket tinytex. Als je R en RStudio hebt binnengehaald moet je de pakketten knitr en rmarkdown binnenhalen. Voor achtergrondinformatie over R, RStudio en RMarkdown vind je hier RRStudioRMarkdowninformatie

Eerder schreef ik al uitgebreid over Reproducable Research en de workshop die Schmidt op 11 Mei 2016 en er waren wat aanvullende materialen beschikbaar zie post Reproducable Research.Delen daarvan breng ik hier nog eens onder de aandacht en ik update de informatie.

Instructies bij het installeren

Voordat je aan het werk gaat, zorg ervoor dat je het volgende hebt gedaan:

  1. Open RStudio.
  2. Installeer en download het devtools R pakket door het volgende commando te runnen.

install.packages("devtools") # Nodig voor deze sessie
library("devtools")          # Nodig voor deze sessie
  1. Check of je de goede versie hebt van R en RStudio door devtools::session_info() in de R console te draaien.
    Hier geeft devtools:: aan om de session_info() functie in R te gebruiken ipv het devtools pakket en de sessionInfo() functie binnen het utils pakket. Het runnen van devtools::session_info() stelt ons in staat de versie van R en RStudio vast te stellen.

Heb je de volgende versie van R en RStudio?

  1. Installeer vervolgens enkele R pakketten die je nodig hebt.

## Installeer de goede pakketten
install.packages("rmarkdown")  # Dit zorgt voor koele dynamische documenten
install.packages("knitr")      # Hier kun je R code Chunks mee runnen
install.packages("ggplot2")    # Voor het plotten van mooie figuren
install.packages("DT")         # Om interactieve HTML tabellen te maken

## Deze pakketten ook laden om er zeker van te zijn dat je de goede pakketten hebt
library("rmarkdown")           # Dit zorgt voor koele dynamische documenten
library("knitr")               # Hier kun je R code Chunks mee runnen
library("ggplot2")             # Voor het plotten van mooie figuren
library("DT")                  # Om interactieve HTML tabellen te maken
  1. Als je de pakketten zonder fouten hebt geladen, kun je beginnen!

Goede bronnen

Deze tutorial kon niet samengesteld worden zonder onderstaande goede bronnen:

  1. De RMarkdown website van RStudio.
  2. Dr. Yuhui Xie’s boek: Dynamic Documents with R and Knitr 2nd Edition [@Xie2015] en zijn Knitr website.
    • HEEL VEEL DANK aan Dr. Xie voor het schrijven van het knitr pakket!!
  3. Dr. Karl Broman’s “Knitr in a Knutshell”.
  4. Cheatsheets released by RStudio.

Sinds 2016 zijn er meer interessante documenten uitgekomen: 1. Het standaardboek over RMarkdown RMarkdown: The Definitive Guide 2. Christopher Gandrud, Reproducable Research with R and RStudio.

Dynamische documenten

Literate programming, zoals dat in het Engels wordt genoemd, is het basisidee achter dynamische documenten en is geintroduceerd door Donald Knuth in 1984. Oorspronkelijk om de broncode en de bijbehorende software documentatie samen te brengen. Tegenwoordig creeren we dynamische documenten waarin het programma of de analyse code samen draaien om tot ‘outputs’ te komen (bv. tabellen, plots, modellen, etc) die worden uitgelegd via narratief schrijven.

Traditioneel gebruikten mensen commentaren om het verhaal in de code file kwijt te kunnen raken (voor R zou dat een .R file zijn). Deze file zou het volgende in kunnen houden:


# Titel:  Relatie tussen Autogewicht en Gasefficientie/of-verbruik
# Door :  Harrie Jonkman  
# Datum:  11 Mei 2016

# Ik verspel dat er een relatie is tussen het gewicht van de auto en de afstand die met de brandstof afgelegd kan worden.  
# Dat test ik met een lineaire analyse van de ''mtcarsdataset' als onderdeel van de R datasets

# Hoe zien de data eruit?
#datatable(mtcars) # Interactieve tabel 

# Is er een relatie tussen het gewicht en de afstand per, in dit geval, gallon?
lm_mpg <- lm(mpg ~ wt, data = mtcars) # Run het lineaire model dat mpg voorspelt op basis van wt
coef_lm_mpg <- coef(summary(lm_mpg))  # Haal de coefficienten eruit voor de tabel die komt 
kable(coef_lm_mpg)                    # Maak een niet-interactieve tabel - een functie in knitr

# Plot de relatie tussen gewicht en afstand in mijl per gallon   
plot <- ggplot(mtcars, aes(x = wt, y = mpg)) + geom_point() + # 
  geom_smooth(method = "lm") + theme_bw() +           # Maak een lineair model en maak het zwart en wit
  xlab("Weight (1000lbs)") + ylab("Miles per Gallon") # Voeg tekst aan de assen toe


# Het lijkt erop dat met een toename van 1000 pounds er een afname is van brandstof gebruik met 5.34 mijl per gallon
# Het eind

De gebruiker zal de commentaren lezen en de codes zelf runnen.

Echter, ‘literate programming’ stelt ons in staat de code te runnen en de resultaten te beschrijven, allemaal in een document dat we kunnen delen. We zouden bijvoorbeeld het volgende kunnen doen:

``` Relatie tussen gewicht van de auto en het brandstofverbruik
Door: Harrie Jonkman
Datum: 27 november 2018

Ik voorspel dat er een relatie is tussen het gewicht en de afstand die met de brandstof kan worden afgelegd. Ik test dat met een lineair model op een dataset in R en zet dit als volgt in het programma.


# Hoe zien de data eruit?
datatable(mtcars) # Interactieve tabel 

# Is er een relatie tussen het gewicht van de auto en de afstand die het kan afleggen met de brandstof?
lm_mpg <- lm(mpg ~ wt, data = mtcars) # Run het lineair model dat mpg voorspelt op basis van wt
coef_lm_mpg <- coef(summary(lm_mpg))  # Haal de co?ffici?nten voor de tabel eruit
kable(coef_lm_mpg)                    # Maak een niet-interactieve tabel - functie in knitr
Estimate Std. Error t value Pr(>|t|)
(Intercept) 37.285126 1.877627 19.857575 0
wt -5.344472 0.559101 -9.559044 0 

# Plot de relatie tussen gewicht en mijl per gallon  
plot <- ggplot(mtcars, aes(x = wt, y = mpg)) + geom_point() + # 
  geom_smooth(method = "lm") + theme_bw() +           # voeg lineair model toe en maak het zwart en wit 
  xlab("Weight (1000lbs)") + ylab("Miles per Gallon") # Voeg tekst aan x en y-as toe

Het lijkt erop dat met elke 1000 pond er een afname is in brandstof gebruik met 5.3444716 mijl per gallon

Het einde

```

Reproduceerbaar onderzoek

Goede uitvoering van reproduceerbaar onderzoek houdt in ieder geval in:

  1. Het hele project in een directory plaatsen die wordt ondersteund door de ‘version control’.
  2. Code en data vrijlaten.
  3. Alles documenteren en de code als documentatie gebruiken!
  4. Figuren, tabellen en de statistiek zijn het resultaat van scripts en codes die in de tekst staan.
  5. Schrijf in de codes de paden die worden gebruikt.
  6. Stel ‘seed’ in zodat een volgende persoon dezelfde resultaten krijgt.
  7. Laat ook informatie zien waarmee de codefile wordt uitgevoerd. Je kunt bijvoorbeeld de devtools::session_info() gebruiken.

Wat het belang van reproduceerbaar onderzoek betreft, zie ook het document van de Koninklijke Nederlandse Academie voor Wetenschappen

Markdown

Om RMarkdown helemaal te begrijpen moeten we het eerst iets over Markdown weten. Dat is een systeem om een simpele, leesbare tekst te maken die eenvoudig kan worden omgezet naar HTML. Markdown is essentieel voor twee dingen:

  1. Een kale tekst die de syntax vormt.
  2. Een software gereedschap dat in Perl is geschreven.
    Het zet de kale tekst om in HTML.

Belangrijkste doel van Markdown:
Maakt de syntax van het orginele (pre-HTML) document zo leesbaar mogelijk.

Zou je deze code liever in HTML lezen?


<body>
  <section>
    <h1>Paklijst voor bergklimmen</h1>
    <ul>
      <li>Bergschoenen</li>
      <li>Klimgordel</li>
      <li>Rugzak</li>
      <li>Touw</li>
      <li>Zelfzekering</li>
    </ul>
  </section>
</body>

Of deze code in Markdown?


# Paklijst voor bergklimmen

* Bergschoenen
* Klimgordel
* Rugzak  
* Touw
* Zelfzekering

Markdown is makkelijker om te lezen!

We zullen meer over de syntax van Markdown praten nadat we RMarkdown hebben geintroduceerd maar laten we ons allereerst beseffen hoeveel makkelijker ons leven is/zal zijn omdat Markdown bestaat! Dank je John Gruber en Aaron Swartz (RIP) voor het ontwikkelen van Markdown in 2004!

RMarkdown

RMarkdown is een variant van Markdown dat het makkelijker maakt om met RStudio dynamische documenten, presentaties en rapporten te maken. Het omvat ‘R code chunks’ (ik laat hier even het Engels staan) om met knitr te gebruiken waarmee makkelijker reproduceerbare (web-based) rapporten gemaakt kunnen worden die automatisch aangepast worden wanneer de onderliggende code is veranderd.

RMarkdown geeft verschillende typen files waaronder onder anderen:

Terwijl er heel veel verschillende documenten kunnen worden geleverd met RMarkdown, ligt hier de nadruk in de eerste plaats op HTML output files omdat die voor mijn onderzoek misschien het meest bruikbaar en flexibel zijn.

Waarom R Markdown?

Een aantrekkelijk gereedschap voor reproduceerbare en dynamische rapporten!

Eenvoudige werkwijze

In het kort, om een rapport te maken:

  1. Open een .Rmd file.
    • Maak een YAML kop (meer hierover zo dadelijk!)
  2. Schrijf de inhoud met RMarkdown syntax.
  3. Neem mee de R code in code chunks of met een inline code.
  4. Draai de document output.

Overzicht van de stappen die RMarkdown maakt om een ‘gerenderd’ document te krijgen:

  1. Maak een .Rmd rapport met ‘R code chunks’ en markdown verhalen (zoals hierboven in stappen beschreven).
  2. Geef de .Rmd-file aan knitr om de ‘R code chunks’ uit te voeren en een nieuwe .md file te maken.
    • Knitr is een pakket binnen R die jou in staat stelt de code binnen RMarkdown documenten uit te voeren zoals HTML, latex, pdf, word en andere document types.
  3. Geef de .md file aan pandoc, die er een definitief document van maakt (b.v. html, Microsoft word, pdf, etc.).
    • Pandoc is een universeel gereedschap om documenten te converteren en zet het ene document type (in dit geval: .Rmd) om in een ander (in dit geval: HTML)

Hoewel dit mogelijk wat ingewikkeld lijkt, kunnen we op de Knit knop drukken boven aan de pagina

of we kunnen de volgende code runnen:

rmarkdown::render("RMarkdown_LesNederlandsBeperkt.Rmd", "html_document")

Maak een .Rmd file

Laten we eens met een RMarkdown gaan werken!

  1. In de menu bar, klik je op File -> New File -> RMarkdown

  2. Dan krijg je het volgende te zien
  1. Klik OK

YAML koppen

YAML staat voor “YAML Ain’t Markup Language” en is eigenlijk de structuur voor de metadata van het document. Het staat tussen twee regels van drie streepjes --- en wordt automatisch omgezet door RStudio. Een eenvoudig voorbeeld:


---
title:  "Analyse Rapport"  
Author:  "Harrie Jonkman"  
date: "1 Maart 2017"  
output:  html_document
---

Het voorbeeld boven zal een HTML document maken. Echter, de volgende opties zijn ook beschikbaar.

Hier ligt de nadruk op HTML files. Echter voel je vrij als je hier wat mee wilt spelen door bv. word en pdf documenten te maken. Presentatie-documenten kennen een wat andere syntax (bv. om aan te geven wanneer de ene dia eindigt en de andere begint) en dan is er nog wat markdown syntax specifiek voor presentaties maar die gaat voorbij het doel van deze workshop.

Markdown Basis

Kijk hiernaar RMarkdown Reference Guide

Haal hier ook informatie vandaan RMarkdown Cheatsheet:

Markdown Basis van RStudio’s RMarkdown Cheatsheet
Markdown Basis van RStudio’s RMarkdown Cheatsheet

Handige tips:

Nog wat wiskundig materiaal:

Beschrijving Code Voorbeelden
Griekse letters $\alpha$ $\beta$ $\gamma$ $\rho$ $\sigma$ $\delta$ $\epsilon$ $mu$ \(\alpha\) \(\beta\) \(\gamma\) \(\rho\) \(\sigma\) \(\delta\) \(\epsilon\) \(\mu\)
Binaire handelingen $\times$ $\otimes$ $\oplus$ $\cup$ $\cap$ \(\times\) \(\otimes\) \(\oplus\) \(\cup\) \(\cap\) \(\times\)
Relationele handelingen $< >$ $\subset$ $\supset$ $\subseteq$ $\supseteq$ \(< >\) \(\subset\) \(\supset\) \(\subseteq\) \(\supseteq\)
Verder $\int$ $\oint$ $\sum$ $\prod$ \(\int\) \(\oint\) \(\sum\) \(\prod\)

Uitdaging: Probeer eens de volgende output te maken:

  1. Vandaag voel ik mij vet omdat ik RMarkdown leer.

  2. honing is heel zoet.

  3. YAS!!!!!!

  4. R2 waarden zijn informatief!

  5. \(R^{2}\) beschrijft de variantie verklaard door het model.

  6. Ik kende geen RMarkdown Vandaag heb ik RMarkdown geleerd

  7. RStudio link

  8. Output van het volgende:

# RMarkdown   
## R   
### Knitr   
#### Pandoc  
##### HTML

  1. \(\sqrt{b^2 - 4ac}\)

  2. \[\sqrt{b^2 - 4ac}\]

  3. \(X_{i,j}\)

  1. Vandaag maak ik een dynamisch document!
  1. Het volgende lijstje:

Chocolade Chips Kook Recept

  1. boter
  2. suiker
    • Een mengsel van bruine en witte suiker maakt het lekkerder
      • mix dat met boter voordat je de eieren eraan toevoegt
  3. eieren
  4. vanille
  5. Mix wat droge ingredienten:
    • meel, zout, bak soda
  6. chocolade chips

Een Code in het document

Er zijn twee manieren om een code in een RMarkdown document op te nemen.

  1. Code in het document: Korte code als een onderdeel van het geschreven document.

  2. Code Chunks: Delen van het document die verschillende programmeer of analyse codes omvatten. Daarmee kan een figuur of tabel worden gemaakt, statistieken worden berekend, pakketten worden geladen, etc.

R Code in het document

Een R code kan in het document wordt gemaakt door een komma hoog achterwaarts (`) en de letter r gevolgd door nog zo’n komma.

Stel dat je een p-waarde rapporteert en je wilt niet terug om de statistische test steeds weer uit te voeren. De p-waarde was eerder 0.0045.
Dit is echt handig als de resultaten op papier moeten worden gezet. Bijvoorbeeld, je hebt een aantal statistieken uitgevoerd voor jouw wetenschappelijke vragen is dit een manier waarop R die waarde in a variabele naam bewaart. Bijvoorbeeld: Wijkt het brandstofverbruik van de automaat significant af de auto met handtransmissie significant af binnen de mtcars data set?


mpg_auto <- mtcars[mtcars$am == 0,]$mpg # automatic transmission mileage
mpg_manual <- mtcars[mtcars$am == 1,]$mpg # manual transmission mileage
transmission_ttest <- t.test(mpg_auto, mpg_manual)

Om de p-waarde vast te stellen kunnen we transmission_ttest$p.value als R code in het document gebruiken.

De p-waarde is dan 0.0013736.

R Code Chunks

R code chunks (nogmaals ik gebruik maar de Engelse benaming hier, sorry)kunnen worden gebruikt om de R output in het document te krijgen of om de code als illustratie zichtbaar te maken.

De anatomie van een code chunk:

Om een R code chunk te plaatsen, kun je met de hand typen door ```{r} gevolgd door ``` op een volgende regel. Je kunt ook de Insert a new code chunk knop gebruiken of de ‘shortcut key’. Dat geeft dan de volgende code chunk:

Een code chunk invoeren
Een code chunk invoeren

```{r}
n <- 10
seq(n)
```

Geef de code chunk een betekenisvolle naam die samenhangt met wat het doet. Hieronder heb ik code chunk 10-random-numbers genoemd:


```{r 10-random-numbers}
n <- 10
seq(n)
```

De code chunk input en output zien er dan als volgt uit:


n = 10
seq(n)

 [1]  1  2  3  4  5  6  7  8  9 10

Knitr

Knitr is een R-pakket dat werkt met

  1. Identificeren van de code zowel van de chunks als in de tekst zelf
  2. Evalueren van de hele code en geeft de resultaten terug
  3. Teruggeven van de geformuleerde resultaten en combineert met de orginele file.

Knitr draait de code zoals die in de R console zou draaien.

Knitr werkt vooral met code chunks.

Een code chunk ziet er als volgt uit:


<div class="layout-chunk" data-layout="l-body">

```r
x <- rnorm(100)  
y <- 2*x + rnorm(100)
```

</div>

Goede praktijken met betrekking tot code chunks:

  1. Benoem/label jouw code chunks!
  2. In plaats van de chunk opties te specificeren in iedere chunk, kun je de algemene chunk opties aan het begin van het document vastzetten.

Chunk Labels

Chunk labels krijgen unieke IDs in een document en zijn goed voor:

Als je de code chunk een naam geef, gebruik dan - of _ tussen woorden voor code chunks labels in plaats van ruimtes. Dat helpt jou en andere gebruikers bij het navigeren in het document.

Chunk labels moeten uniek zijn in het document - anders zal er een fout optreden!

Chunk Opties

Druk tab als tussen de haakjes code chunk opties omhoog komen.

Er zijn teveel chunk opties om hier te behandelen. Kijk na deze workshop nog eens wat rond voor deze opties.

Een mooie website om dat op te doen is Knitr Chunk Options.

Uitdaging
Draai de code chunk hieronder en speel wat met de volgende knitr code chunk opties:

Sla je resultaten op in markdown.
Opgelet: Wees er zeker van dat je jouw chunks een naam geeft!


1+1
2*5
seq(1, 21, by = 3)
head(mtcars)

Enkele voorbeelden voortbouwend op de chunk hierboven

Resultaten van results="markup", collapse = TRUE}:


1+1
[1] 2
2*5
[1] 10
seq(1, 21, by = 3)
[1]  1  4  7 10 13 16 19
head(mtcars)
                   mpg cyl disp  hp drat    wt  qsec vs am gear carb
Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1
Resultaten van results="asis", collapse = TRUE}: 

1+1

[1] 2


2*5

[1] 10


seq(1, 21, by = 3)

[1] 1 4 7 10 13 16 19


head(mtcars)

               mpg cyl disp  hp drat    wt  qsec vs am gear carb

Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4 Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4 Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1 Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1 Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2 Valiant 18.1 6 225 105 2.76 3.460 20.22 1 0 3 1

Globale opties

Het kan zijn dat je dezelfde chunk settings wilt handhaven voor het gehele document. Het kan daarom handig zijn om de opties in een keer te typen in plaats van het iedere keer weer voor een chunk te moeten doen. Om dat te doen kun je de globale chunk opties bovenaan het document vaststellen.


knitr::opts_chunk$set(echo = FALSE, 
                      eval = TRUE, 
                      message = FALSE,
                      warning = FALSE, 
                      fig.path = "Figures/",
                      fig.width = 12, 
                      fig.height = 8)

Als je bijvoorbeeld met iemand samenwerkt die de code niet wil zien, kun je schrijven eval = TRUE en echo = FALSE gebruiken zodat de code wel gedraaid wordt maar niet getoond. In aanvulling wil je misschien message = FALSE en warning = FALSE gebruiken zodat jouw samenwerkingspartner geen enkele boodschap of waarschuwing van R ziet.

Als je figuren wilt opslaan en bewaren in een subdirectory binnen het project, gebruik dan fig.path = "Figures/". Hier verwijst de "Figures/" naar een folder Figures binnen de huidige directory waar de figuur die gemaakt wordt in het document wordt opgeslagen.
Opgelet: de figuren worden niet standaard opgeslagen.

Globale chunk opties zullen voor de rest van het documenten worden vastgezet. Als je wilt dat een bepaalde chunk afwijkt van de globale opties, maak dat aan het begin van die bepaalde chunk duidelijk.

Figuren

Knitr maakt vrij eenvoudig figuren. Als een analyse code binnen een chunk een bepaald figuur moet produceren, dan zal hij dat in het document afdrukken.

Enkele knitr chunk opties gerelateerd aan figuren:

Een enkelvoudig figuur maken:

Met fig.align = "center"


ggplot(mtcars, aes(x = mpg)) + xlab("Miles per Gallon") +
    geom_histogram(bins = 30, fill = "cornflowerblue", color = "black") +
    geom_vline(xintercept=mean(mtcars$mpg), col="red")

Met fig.align = "right"


ggplot(mtcars, aes(x = mpg)) + xlab("Miles per Gallon") +
    geom_histogram(bins = 30, fill = "cornflowerblue", color = "black") +
    geom_vline(xintercept=mean(mtcars$mpg), col="red")

Met fig.align = "left"


ggplot(mtcars, aes(x = mpg)) + xlab("Miles per Gallon") +
    geom_histogram(bins = 30, fill = "cornflowerblue", color = "black") +
    geom_vline(xintercept=mean(mtcars$mpg), col="red")

Met fig.width = 2, fig.height = 2


ggplot(mtcars, aes(x = mpg)) + xlab("Miles per Gallon") +
    geom_histogram(bins = 30, fill = "cornflowerblue", color = "black") +
    geom_vline(xintercept=mean(mtcars$mpg), col="red")

Met fig.width = 10, fig.height = 10


ggplot(mtcars, aes(x = mpg)) + xlab("Miles per Gallon") +
    geom_histogram(bins = 30, fill = "cornflowerblue", color = "black") +
    geom_vline(xintercept=mean(mtcars$mpg), col="red") 


myplots <- list()  # new empty list
for(i in 1:ncol(mtcars)){
  col <- names(mtcars)[i]
  ggp <- ggplot(mtcars, aes_string(x = col)) +
    geom_histogram(bins = 30, fill = "cornflowerblue", color = "black") +
    geom_vline(xintercept = mean(mtcars[[col]]), col = "red") 
  myplots[[i]] <- ggp  # add each plot into plot list
}
multiplot(plotlist = myplots, cols = 4) # must load in multiplot function from the Rcookbook see http://www.cookbook-r.com/Graphs/Multiple_graphs_on_one_page_(ggplot2)/

Tabellen

Tabellen kunnen in Markdown voor nogal wat hoofdpijn kosten. We gaan er hier verder niet op in. Als je meer wilt leren over Markdown-tabellen kijk naar documentation on tables op de RMarkdown website.

Er zijn enkele tabeltypen die handig kunnen zijn. Hier zullen we ons vorig voorbeeld gebruiken van de mtcars data

In zijn Knitr in a Knutshell introduceert Dr. Karl Broman: kable, panderen xtable en vooral die eerste twee deden mij plezier:

kable en pander tabellen zijn mooi en handig bij het maken van niet-interactieve tabellen:


kable(head(mtcars, n = 4)) # kable table with 4 rows
mpg cyl disp hp drat wt qsec vs am gear carb
Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4
Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4
Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1
Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1 

# Pander table
# install.packages("pander") # install pander first
library(pander)
pander(head(mtcars, n = 4))
Table continues below
  mpg cyl disp hp drat wt qsec vs am
Mazda RX4 21 6 160 110 3.9 2.62 16.46 0 1
Mazda RX4 Wag 21 6 160 110 3.9 2.875 17.02 0 1
Datsun 710 22.8 4 108 93 3.85 2.32 18.61 1 1
Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0
  gear carb
Mazda RX4 4 4
Mazda RX4 Wag 4 4
Datsun 710 4 1
Hornet 4 Drive 3 1

Zie ook hoe je mooie tabellen kunt maken hierKable

HTML Widgets

Met de uitgave van de nieuwe RMarkdown v2 is het makkelijker dan ooit tevoren om HTML Widgets te gebruiken. Volg de link om uit te zoeken in welke widgets jij ge?nteresseerd bent!

Onlangs ontdekte ik bijvoorbeeld het DT pakket waarmee tabellen interactief kunnen worden gemaakt in de HTML output. Daarbij levert Plotly for R echt mooie interactieve grafieken op, welke gebaseerd zijn op Plotly.

Cool, of niet?


# DT table = interactive
# install.packages("DT") # install DT first
library(DT)
datatable(head(mtcars, n = nrow(mtcars)), options = list(pageLength = 5)) 

# plotly
# install.packages("plotly")
library(plotly)
mtcars$car <- row.names(mtcars)
plot_ly(mtcars, x = wt, y = mpg, 
        text = paste("Car: ", car),
        mode = "markers", color = wt, size = wt)

Error in plot_ly(mtcars, x = wt, y = mpg, text = paste("Car: ", car), : object 'wt' not found

Spelling controleren

In de spelling kunnen natuurlijk altijd fouten zitten en daarom kan het nodig zijn dat we onze spelling in het document willen controleren. Er zijn twee manieren om de spelling te controleren:

  1. Druk op de “ABC check mark” links van de vergrootglasknop in RStudio.
  2. Gebruik de aspell() functie van het utils pakket. Je kunt dan echter beter de code chunks overslaan. De aspell() functie kan een filter functie overnemen om bepaalde regels in de files over te slaan en kan worden gebruikt met de knit_filter() die ontworpen is om de code chunks in een file over te slaan.

Knitr Thema’s

Het knitr-syntax-thema kan worden aangepast of helemaal naar de hand worden gezet. Als je de standaardthema’s niet wilt, gebruik dan het knit_theme om het te veranderen. Er zijn 80 thema’s opgenomen binnen knitr en we kunnen de namen ervan zien door knit_theme$get().

Wat zijn de eerste 30 knitr thema’s?


head(knit_theme$get(), 30)

 [1] "acid"          "aiseered"      "andes"         "anotherdark"  
 [5] "autumn"        "baycomb"       "bclear"        "biogoo"       
 [9] "bipolar"       "blacknblue"    "bluegreen"     "breeze"       
[13] "bright"        "camo"          "candy"         "clarity"      
[17] "dante"         "darkblue"      "darkbone"      "darkness"     
[21] "darkslategray" "darkspectrum"  "default"       "denim"        
[25] "dusk"          "earendel"      "easter"        "edit-anjuta"  
[29] "edit-eclipse"  "edit-emacs"

Wij kunnen knit_theme$set() gebruiken om het thema vast te zetten. Om het thema op fruit vast te zetten, kunnen we de bijvoorbeeld de volgende code gebruiken:


knit_theme$set("fruit")

Hier is de link naar jouw favoriete thema 80 knitr highlight themes.

Inhoudsopgave

Een inhoudsopgave kan aan het gerenderd document worden toegevoegd door de toc optie in de YAML kop te gebruiken.

Opties hierbij:

Bijvoorbeeld:


output:
  html_document:
    toc: true
    toc_depth: 2
---

Uitdaging: Maak de YAML kop voor een HTML document die het volgende inhoudt:

Thema’s

RMarkdown heeft verschillende opties voor de HTML documenten. Enkele mogelijkheden waaruit kan worden gekozen, hier met de Engelse termen:

De HTML output thema’s komen van Bootswatch library. Valide HTML themes omvatten de volgende:

Highlight specificeert de wijze waarop de syntax stijl oplicht. Stijlen die mogelijk zijn omvatten de volgende:

Smart indiceert of de typografisch correcte output wordt weergegeven, zet rechte aanhalingstekens om in gekru, — rechte aanhalingstekens, – om in gekrulde aanhalingstekens en … in ellipsen. Smart is standaard ingesteld.

Bijvoorbeeld:


---
output:
  html_document:
    theme: slate
    highlight: tango
---

Als je wilt kun je ook jouw eigen stijl-thema produceren en gebruiken. Als je dat zou doen, zou de output sectie van jouw YAML kop er z’on beetje zo uitzien:


output:
  html_document:
    css: styles.css

Als je nog wat verder wilt gaan en jouw eigen thema wilt schrijven in aanvulling op het oplichten, zou de YAML kop er beetje zo uitzien:


---
output:
  html_document:
    theme: null
    highlight: null
    css: styles.css
---

Hier is een link naar Pr?sance en Stijl in de HTML output.

Bibliografie

Het is ook mogelijk om een bibliografie file in de YAML kop mee te nemen. Bibliografie formats die door Pandoc gelezen kunnen worden zijn:

Format File extension
MODS .mods
BibLaTeX .bib
BibTeX .bibtex
RIS .ris
EndNote .enl
EndNote XML .xml
ISI .wos
MEDLINE .medline
Copac .copac
JSON citeproc .json

Om een bibliografie in RMarkdown te maken, zijn er twee files nodig:

  1. Een bibliografie file met informatie over elke referentie.
  2. Een citaat stijl taal (CSL) om het format de referentie te bepalen.

Een voorbeeld YAML kop met een bibliografie en een citaat stijl taal (CSL) file is:


output: html_document
bibliography: bibliography.bib
csl: nature.csl

Bekijk de erg behulpzame webpagina van het R Core team op bibliographies and citations.

Als je R pakketten wilt citeren, heeft knitr zelfs een functie die write_bib() heet en die .bib overzicht van R pakketten kan leveren. Het wordt zelfs in een file geschreven!


write_bib(file = "r-packages.bib") # will write all packages  
write_bib(c("knitr", "ggplot2"), file = "r-packages2.bib") # Only writes knitr and ggplot2 packages

Plaatsen

De bibliografie wordt automatisch aan het einde van het document geplaatst. Daarom moet je jouw .Rmd document met # Referenties eindigen zodat de bibliografie naar de kop voor bibliografie komt.

Stylen

Citation Sylte Language (CSL) is een op XML-gebaseerde taal die het format van citaten en bibliografie?n vaststelt. Referentie management programma’s zoals Zotero, Mendeley en Papers gebruiken allemaal CSL.

Zoek jouw favoriete tijdschrift en CSL in de Zotero Style Repository, waar nu meer dan 8,152 CSLs inzitten. Is er een stijl waar je naar zoekt en die er niet in zit?


output: html_document
bibliography: bibliography.bib
csl: nature.csl

In de github repo voor deze workshop heb ik de nature.csl en the-isme-journal.csl toegevoegd om mee te spelen. Download anders een stijl van de Zotero Style Repository!

Citaten

Citaten gaan tussen vierkante haakjes [ ] en worden afgescheiden door punt-komma’s’ ;. Elk citaat moet een sleutel hebben, samen de @ + de citaat identificatie van de database vormen en die optioneel a prefix, a locator en a suffix hebben. Om te controleren wat de citaatsleutel is van een referentie, werp dan een blik op de .bib file. Hier in die file, kun je de sleutel voor elke referentie veranderen. Echter, wees er wel van bewust dat elke ID uniek is!

Hier zijn wat voorbeelden met bijpassende code in het Engels:

Het is cool dat de enige refenties die aan het document worden toegevoegd degene zijn die jijzelf citeert!

Publiceren via RPubs

Als je een keer een mooi dynamisch document hebt gemaakt wil je dat mogelijk delen met anderen. Een mogelijkheid om het te delen met de wereld is om het te hosten op RPubs. Met RStudio kan dit heel makkelijk! Doe het volgende:

  1. Maak een aansprekend .Rmd document.
  2. Klik op de knop om jouw gerenderd HTML document te puliceren.
  3. In de rechter bovenhoek van het previewscherm klik je op de publiceerknop en volg je de aanwijzingen.
    • Opgelet: Je moet een RPubs profiel hebben aangemaakt.
  4. Als je het profiel hebt, let dan op het volgende:
    • De titel van het document.
    • Een beschrijving van het document.
    • De URL waar de website wordt gehost.
      • Opgelet: Het begin van de URL zal zijn: www.rpubs.com/your_username/name_of_your_choice

RPubs vernieuwen

Als je veranderingen in het document wilt aanbrengen is het makkelijk om de webpagina te vernieuwen. Als je een keer jouw aangepaste documentg hebt gerenderd klik je op de knop rechtsboven in de hoek van de preview scherm. Het aangepaste document zal dezelfde URL hebben als het orginele document.

Enkele RMarkdown-documenten

Net als \(\Latex\) leent RMarkdown zich voor het opmaken van hele verschillende wetenschappelijke producten. Van een aantal belangrijke artikele heb ik wat voorbeelden gemaakt. Als basis heb ik een klein rapport van twee collega’s van mij genomen. Voor mensen die hiermee willen werken, is er een syntax. Met behulp daarvan kun je het product makkelijk en eenvoudig maken.

Artikel

Iedereen die wel eens een wetenschappelijk artikel maakt, weet dat hij of zij soms tegen ingewikkelde zaken aanloopt. De consistente opbouw bijvoorbeeld, het toevoegen van een tabel of een figuur, de referenties goed plaatsen. Als je in Word werkt is het soms lastig als je van volgorde verandert. Bij RMarkdown kun je het pakket rticlesbinnenhalen. Dan krijg je enkele templates waaruit je een keuze kunt maken. Hier JSS-voorbeeld het artikel voor Journal of Statistical Software.

Boek

Een boek bestaat uit verschillende onderdelen, bijvoorbeeld uit een een inhoudsopgave, de hoofdstukken en de literatuur. Hier wordt een stramien voor de opbouw van een boek aangeboden dat eenvoudig is aan te passen. Van het rapprt heb ik een klein boekje gemaakt, dat vind je hier DenHaagboekhtml

Het is dan ook makkelijk om van hetzelfde een eboek te maken. Dat eboek vind je hier EboekDenHaag

Rapport

Van hetzelfde onderzoek heb ik ook een fraai vormgegeven rapport gemaakt in de Tufte-stijl. Dat staat hier DenHaagRapport

Presentatie

De presentaties kunnen er ook net wat strakker uitzien. Hier geef ik twee voorbeelden Beamer en ook in een andere stijl kun je het zelf draaien ioslides

Een blog en website

Dit blog is met het pakket Radix gemaakt. Van Den Haag heb ik ook een blog gemaakt en dat vind je hier.Blog

Tutorial

Over RMarkdown heb ik eerder deze tutorial van Schmidt bewerkt, zie Dynamische documenten

Een dashboard

Een dashboard is een fraaie manier om kort maar krachtig enkele resultaten te presenteren. Zie hier Dashboard

Tot slot

Hartelijke dank Marian Schmidt voor het opzetten van de workshop RMarkdown waar ik heel veel van heb geleerd en in dit document gebruik van heb gemaakt. Hartelijk dank natuurlijk ook naar Yihui Xie die zoveel hieromtrent heeft ontwikkeld en dit in alle openbaarheid met anderen deelt.