R Markdown-tutorial voor beginners

In dit artikel bekijken we een essentiël en handig data-sciencepakket dat elke R-gebruiker zou moeten kennen—R Markdown. We leren wat R Markdown is, welke voordelen het biedt, waar het voor wordt gebruikt, hoe je het installeert, welke mogelijkheden het biedt voor werken met code, tekst en datavisualisaties, welke syntaxis het gebruikt, de uitvoerformaten voor R Markdown-documenten en hoe je zulke documenten rendert en deelt met je samenwerkers.

Omdat R Markdown bijzonder goed is afgestemd op de geïntegreerde ontwikkelomgeving (IDE) RStudio, gebruiken we deze IDE in dit hele artikel. De RStudio-tutorial geeft de nodige uitleg over hoe je RStudio installeert en ermee begint te werken.

Laten we erin duiken!

Wat is R Markdown?

R Markdown is een gratis en open-source R-pakket dat een werkplek biedt voor het maken van data-scienceprojecten. Het grootste voordeel van R Markdown is dat je code, tekst en datavisualisaties kunt combineren in één gepolijst, deelbaar en volledig reproduceerbaar document dat in een breed scala aan uitvoerformaten kan worden gerenderd, zowel statisch als interactief.

Enkele populaire uitvoerformaten zijn HTML, PDF, Microsoft Word, presentaties, applicaties, websites, dashboards, rapporten, templates, artikelen, boeken, enzovoort.

Daarnaast maakt R Markdown eenvoudige versiebeheertracking mogelijk en ondersteunt het naast R ook veel andere programmeertalen, waaronder Python en SQL.

Wil je dieper ingaan op het schrijven van dynamische rapporten met R Markdown, dan is de cursus Reporting with R Markdown de juiste plek om te beginnen.

R Markdown installeren

Als je R Markdown buiten RStudio gebruikt, installeren we het op dezelfde manier als elk ander R-pakket vanaf de Comprehensive R Archive Network (CRAN)-repository:

install.packages("rmarkdown")

Na installatie moeten we het pakket laden in de werkende R-omgeving:

library(rmarkdown)

Als we in plaats daarvan met R Markdown in RStudio werken—wat we in deze tutorial doen—hoeven we het rmarkdown-pakket niet expliciet te installeren en te laden. Door in de menubalk van RStudio op File—New File—R Markdown te klikken, wordt een nieuw R Markdown-document geopend. Op dit moment kunnen we een melding Install Required Packages krijgen, als volgt:

Na het bevestigen van de installatie van de vereiste pakketten geven we in een nieuw pop-upvenster een documenttitel en de naam van de auteur op (beide optioneel maar aanbevolen), laten we de overige instellingen zoals ze zijn en klikken we op OK:

Standaard R Markdown-document

In de vorige sectie hebben we een nieuw R Markdown-document geopend in RStudio. Het ziet er als volgt uit:

We zien dat het de titel, de naam van de auteur, de huidige datum en het standaarduitvoerformaat bevat die we in het pop-upvenster hebben opgegeven bij het openen. Vervolgens staan er enkele voorbeelden in van de basis-syntaxis die R Markdown gebruikt, zoals het toevoegen en opmaken van codechunks, het toevoegen van koppen, links invoegen, tekst benadrukken en plots genereren.

We gaan de verschillende functionaliteiten van R Markdown en hun syntaxis gedetailleerder bekijken. Voor nu slaan we dit standaardbestand op en renderen we het vervolgens in het geselecteerde uitvoerformaat (in ons geval HTML) om te zien hoe het eruitziet.

Om het bestand op te slaan, klikken we in de menubalk van RStudio op File—Save As....

LET OP: de naam van het R Markdown-document die we eerder hebben opgegeven, is niet hetzelfde als de bestandsnaam. We moeten het bestand opslaan in de projectmap en het vervolgens regelmatig tussentijds opslaan (File—Save) terwijl we ermee werken.

Om het opgeslagen bestand in het geselecteerde uitvoerformaat (HTML) te renderen, klikken we op Knit in de werkbalk van het bestand:

Zo ziet ons standaard R Markdown-document eruit in HTML-formaat:

Tekstopmaak in R Markdown

Vaak vormt tekst het grootste deel van een data-scienceproject. Het is dus belangrijk om te weten hoe je die in R Markdown opmaakt zodat die leesbaar, effectief en overtuigend is.

Wil je leren hoe je R gebruikt voor data-analyse en data science en zowel je R-programmeer- als data-sciencevaardigheden laten groeien, bekijk dan deze beginnersvriendelijke en complete carrièrepaden:

• Data Analyst with R
• Data Scientist with R

Koppen

We kunnen verschillende niveaus van koppen toevoegen aan ons R Markdown-document met behulp van het hekje (#). De syntaxis is als volgt:

# Kop 1 (hoofdtitel)

## Kop 2 (sectie)

### Kop 3 (subsectie)

enz.

Wanneer gerenderd, zien de bovenstaande koppen er als volgt uit:

Tekstaccentuering

R Markdown maakt het mogelijk om verschillende soorten nadruk aan tekst toe te voegen, zoals cursief, vet, doorhalen, superscript of subscript, als volgt:

• *cursief* of _cursief_
• **vet** of __vet__
• ~~doorhalen~~
• tekst^superscript^
• tekst~subscript~

Hieronder zie je hoe deze soorten nadruk eruitzien in de gerenderde vorm:

Lijsten

Om een ongenummerde lijst te maken, gebruiken we een van de volgende drie syntaxisvormen:

* Item 1* Item 2* Item 3

of:

- Item 1- Item 2- Item 3

of:

+ Item 1+ Item 2+ Item 3

In alle gevallen is het gerenderde resultaat hetzelfde:

Om een genummerde lijst te maken, gebruiken we de volgende syntaxis:

1. Item 12. Item 23. Item 3

Het gerenderde resultaat ziet er vrijwel hetzelfde uit, met een inspringing vóór elk nummer.

Let op: als we een item uit een genummerde lijst verwijderen, een nieuw item toevoegen of gewoon een fout maken in een van de nummers (bijv. als we 20. in plaats van 2. schrijven in het bovenstaande voorbeeld), worden de nummers automatisch gecorrigeerd en getoond zoals bedoeld:

Blokcitaten

Voor blokcitaten gebruiken we het >-symbool vóór het eerste teken van de te citeren tekst:

> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam hendrerit nisi sed sollicitudin pellentesque. Nunc posuere purus rhoncus pulvinar aliquam. Ut aliquet tristique nisl vitae volutpat. Nulla aliquet porttitor venenatis. Donec a dui et dui fringilla consectetur id nec massa. Aliquam erat volutpat. Sed ut dui ut lacus dictum fermentum vel tincidunt neque.

Dit wordt gerenderd als:

We voegen een lege regel toe na een geciteerd blok om het af te sluiten.

Links

Als we een link als direct pad willen opnemen, moeten we het linkpad tussen de < en > zetten. Bijvoorbeeld, de volgende constructie:

<https://www.google.com/>

wordt gerenderd als:

https://www.google.com/

Als we in plaats daarvan een link aan een woord of kort tekstfragment willen hangen, gebruiken we de volgende syntaxis (opnieuw met de website van Google als voorbeeld):

[Google](https://www.google.com/)

Dit wordt gerenderd als:

Google

Afbeeldingen

Om een afbeelding in onze tekst op te nemen, gebruiken we een van de volgende benaderingen:

1. Als we een afbeelding van internet willen toevoegen:


2. Als het afbeeldingsbestand is opgeslagen in de projectmap waar ons R Markdown-document is opgeslagen:


3. Als het afbeeldingsbestand op onze computer is opgeslagen maar buiten de projectmap:


Alt-tekst geeft korte informatie over wat er op de afbeelding te zien is en wordt gebruikt in gevallen waarin een gebruiker de afbeelding om wat voor reden dan ook niet kan zien op de pagina.

Laten we de eerste aanpak in de praktijk brengen voor een Pixabay-afbeelding, met de image-URL https://cdn.pixabay.com/photo/2018/12/02/10/07/web-3850917_1280.jpg:


Wanneer we het document renderen, wordt de afbeelding weergegeven:

Witregels en pagina-einden

Er zijn verschillende soorten onderbrekingen in R Markdown:

1. Regeleinde—om een nieuwe regel te beginnen. Voer je in door de vorige regel te beëindigen met een backslash (\).
2. Alinea-einde—om een nieuwe alinea te beginnen. Voer je in door de vorige alinea te beëindigen met twee spaties.
3. Slide-onderbreking—om een nieuwe slide te beginnen in slide-gebaseerde uitvoerformaten (presentaties) of een nieuwe sectie in alle andere formatten. Voer je in door een horizontale lijn (***) in het document te plaatsen.
4. Pagina-einde—om een nieuwe pagina te beginnen, in die uitvoerformaten waar dit van toepassing is, bijvoorbeeld in Microsoft Word. Voer je in door het commando \newpage in het document te plaatsen.

Laten we de eerste drie soorten onderbrekingen in de praktijk brengen. Hieronder staat een stuk Lorem ipsum-tekst met enkele R Markdown-onderbrekingssymbolen toegevoegd:

Lorem ipsum dolor sit amet, consectetur adipiscing elit.\Nam hendrerit nisi sed sollicitudin pellentesque.

Nunc posuere purus rhoncus pulvinar aliquam.

***

Ut aliquet tristique nisl vitae volutpat.

Zo wordt dit gerenderd in een HTML-document:

Lorem ipsum dolor sit amet, consectetur adipiscing elit.Nam hendrerit nisi sed sollicitudin pellentesque.

Nunc posuere purus rhoncus pulvinar aliquam.

Ut aliquet tristique nisl vitae volutpat.

Code opmaken en uitvoeren in R Markdown

Code is een ander essentieel onderdeel van elk data-scienceproject. In R Markdown kunnen we code uitvoeren (en niet alleen in de programmeertaal R), zowel code als de uitvoer tonen, alleen code tonen en de uitvoer verbergen, alleen uitvoer tonen en de broncode verbergen, enzovoort.

Het beginnersvriendelijke carrièrepad R Programmer en het skill track R Programming zijn nuttige bronnen om je R-codeervaardigheden te leren, oefenen en aanscherpen.

Codechunks

Om een blok R-code in R Markdown op te maken en uit te voeren, plaatsen we het tussen een paar van drie backticks, waarbij de eerste drie backticks gevolgd worden door een r tussen accolades. Bijvoorbeeld:

```{r}
print("Hello, World!")
```

Als we ons document renderen zonder de code uit te voeren, ziet onze codechunk er als volgt uit:

Programmeertaal

Wanneer we met R Markdown werken, zijn we niet beperkt tot alleen R, want dit pakket ondersteunt ook veel andere programmeertalen. Om een stuk code in een andere programmeertaal uit te voeren, geven we de naam van die taal op in plaats van de r tussen accolades. Daarnaast moeten we mogelijk extra pakketten installeren en laden in de werkende R-omgeving.

Om bijvoorbeeld Python in R Markdown te kunnen gebruiken, moeten we het reticulate-pakket installeren en laden. Dat maakt tweerichtingscommunicatie mogelijk (zoals variabelen aanmaken en benaderen) tussen Python en R in hetzelfde R Markdown-document.

Laten we het codefragment uit de vorige sectie herschrijven in Python (na het installeren en laden van het reticulate-pakket):

```{python}
print("Hello, World!")
```

Codechunks uitvoeren

Om een codechunk of geselecteerde regels daarvan uit te voeren wanneer je met R Markdown in RStudio werkt, klik je op de knop Run op de werkbalk van het document en kies je de gewenste optie in de keuzelijst:

In de bovenstaande afbeelding zie je dat elke optie om uit te voeren een sneltoets heeft die we kunnen gebruiken in plaats van telkens de keuzelijst te openen.

Codechunks benoemen

Hoewel het niet verplicht is, is het een goede gewoonte om codechunks een naam te geven. Dat kan in veel gevallen nuttig zijn: om codechunks te refereren in het document, bij het debuggen van code, om tussen codechunks te navigeren, enzovoort. Chunks benoemen wordt vooral belangrijk als we met een lang document werken dat veel codechunks bevat.

We voegen de naam van een codechunk toe tussen accolades, direct na de taalnaam, gescheiden door een spatie. De naam van een codechunk mag geen spaties bevatten.

In het onderstaande voorbeeld hebben we de naam hello_world aan de chunk toegevoegd:

```{r hello_world}
print("Hello, World!")
```

Opties voor codechunks

Met opties voor codechunks kunnen we de controle nemen over code-evaluatie, uitvoer, opmaak, caching, animatie (indien van toepassing) en plots (indien van toepassing)—dit alles per individuele codechunk. We kunnen meerdere chunkopties aan dezelfde codechunk toevoegen. Qua syntaxis plaatsen we chunkopties tussen accolades direct na de codenaam (indien beschikbaar; anders na de taalnaam), gescheiden daarvan en onderling door een komma.

Er zijn veel chunkopties beschikbaar in R Markdown. Elke optie heeft een standaardwaarde, maar als we ze gebruiken, willen we meestal een andere waarde dan de standaard. Laten we kijken naar de meest populaire chunkopties en hun waarden die voor ons interessant kunnen zijn:

• echo=FALSE—de code zelf wordt niet getoond in het einddocument, alleen de uitvoer.
• eval=FALSE—de code in de codechunk wordt niet uitgevoerd.
• include=FALSE—de codechunk wordt uitgevoerd maar niet opgenomen in het einddocument.
• results—de standaardwaarde is "markup"; andere waarden zijn:
• "hide"—de uitvoer van de code wordt verborgen in het einddocument
• "hold"—de uitvoer van de code wordt vertraagd getoond, pas nadat de hele codechunk is uitgevoerd
• "asis"—de uitvoer van de code wordt doorgegeven zonder opnieuw op te maken.
• message=FALSE—de berichten die door de code worden geproduceerd, worden niet getoond.
• error=FALSE—de fouten die door de code worden geproduceerd, worden niet getoond.
• warning=FALSE—de waarschuwingen die door de code worden geproduceerd, worden niet getoond.
• highlight=FALSE—de code wordt niet gesyntaxhighlight in het einddocument.
• prompt=TRUE—het >-symbool wordt toegevoegd aan het begin van elke codelijn die in het einddocument wordt getoond.

Hieronder staan enkele voorbeelden van codechunks die eerst in R Markdown in RStudio zijn uitgevoerd en vervolgens in het einddocument zijn gerenderd:

Code in R Markdown:

Uitvoer in het einddocument:

Inline code

Met inline code kunnen we korte stukken code rechtstreeks in de tekst van ons R Markdown-document opnemen—ze worden uitgevoerd en hun uitvoer wordt ingebed in de tekst getoond. De syntaxis van inline code is r <code>.

Hieronder staat een eenvoudig voorbeeld van tekst met inline code:

There are `r 1+6` colors of the rainbow.

en zo wordt dit gerenderd in het einddocument:

There are 7 colors of the rainbow.

In de praktijk wordt inline code gebruikt om informatie over de data te aggregeren en helpt het fouten te vermijden die gemakkelijk kunnen optreden als we de cijfers handmatig invoegen of als de data verandert.

Plotten in R Markdown

Plotten in R Markdown houdt in dat je code uitvoert die grafieken genereert. Alles wat we tot nu toe hebben besproken over code opmaken en uitvoeren in R Markdown, met uitzondering van inline code, geldt dus ook voor plotten. Het belangrijkste verschil is dat de uitvoer van zulke code grafieken zal zijn in plaats van alleen tekst en getallen.

Het skill track Data Visualization with R helpt je de vaardigheden te ontwikkelen die nodig zijn om data in R te analyseren en te visualiseren en zo betere datagedreven verhalen te vertellen.

Om plots in R Markdown aan te passen, gebruiken we, net als in reguliere R, de tools van R-datavisualisatiepakketten, evenals de plot()-functie van base R.

Om het plotgedrag in een R Markdown-document te bepalen, kunnen we echter chunkopties gebruiken die alleen betrekking hebben op plotten. De meeste daarvan zijn behoorlijk specifiek en vallen daarom buiten de scope van deze "aan de slag"-tutorial. Laten we dus kijken naar enkele basis-chunkopties die handig kunnen zijn bij het plotten in R Markdown:

• fig.show—de standaardwaarde is "asis"; andere waarden zijn:
• "hide"—de plots worden gegenereerd maar niet opgenomen in het einddocument
• "hold"—de plots worden vertraagd getoond, pas nadat de hele codechunk is uitgevoerd
• "animate"—alle plots van de codechunk worden samengevoegd tot een animatie.
• fig.width—de plotbreedte in inches, standaard 7.
• fig.height—de plothoogte in inches, standaard 7.
• fig.align—de manier waarop plots worden uitgelijnd in het einddocument: "left", "center" of "right".
• fig.cap—een figuurbijschrift als tekenreeks.
• fig.path—een pad naar de map waar de plotbestanden die door de codechunk zijn gemaakt, moeten worden opgeslagen.
• fig.ext—de extensie van de plotbestanden die door de codechunk zijn gemaakt.

Hieronder staan enkele voorbeelden van het gebruik van plot-specifieke codechunks bij het plotten in R Markdown, inclusief de broncode en de gerenderde uitvoer:

Code in R Markdown:

Uitvoer in het einddocument:

Uitvoerformaten

Tot nu toe hebben we alleen het HTML-document (html_document) beschouwd als uitvoerformaat voor het einddocument. R Markdown biedt echter veel andere uitvoerformaten, waaronder Microsoft Word, Microsoft PowerPoint, PDF, interactieve R-notebooks, dashboards, enzovoort.

Zo zijn de uitvoerformaten die in R Markdown beschikbaar zijn voor het maken van documenten onder meer html_document, pdf_document, word_document, github_document, html_notebook, html_vignette, enz. Voor het maken van presentaties kunnen we in plaats daarvan de volgende uitvoerformaten gebruiken: powerpoint_presentation, ioslides_presentation, slidy_presentation en beamer_presentation.

Om een uitvoerformaat voor ons R Markdown-document in te stellen, wijzen we de overeenkomstige waarde toe aan de output-instelling in de documentkop (ook wel de YAML-header genoemd, waar YAML staat voor yet another markup language). In ons werkende R Markdown-document is het uitvoerformaat bijvoorbeeld ingesteld op html_document, wat ook het standaarduitvoerformaat in R Markdown is:

Om dit te wijzigen, vervangen we html_document door het gewenste uitvoerformaat (pdf_document, word_document, powerpoint_presentation, enz.). Wanneer we nu op Knit in de werkbalk van het bestand klikken, renderen we ons document in het geselecteerde uitvoerformaat.

R Markdown-documenten publiceren

Om een R Markdown-document te publiceren, klikken we in de menubalk van RStudio op File—Publish en kiezen we waar we het willen publiceren:

Daarna volgen we de verdere instructies, die afhangen van onze eerdere keuze, en klikken we op Publish. Nu is ons document klaar om te delen met onze samenwerkers.

Conclusie

Samenvattend: in dit artikel leerden we hoe je aan de slag gaat met R Markdown. Eerst definieerden we wat R Markdown is en waar het voor wordt gebruikt. Daarna bespraken we hoe je R Markdown installeert, hoe je tekst en de verschillende componenten ervan opmaakt, hoe je code opmaakt en uitvoert, hoe je grafieken genereert, welke uitvoerformaten R Markdown biedt, hoe je een werkdocument in een van die formaten rendert en hoe je het einddocument publiceert om het verder te delen met collega’s.

Wil je praktisch aan de slag met R Markdown, bekijk dan onze Reporting with R Markdown-cursus, die je helpt inzichten uit data te halen en je bevindingen te publiceren als een PDF, HTML-bestand of Shiny-app.