quarto
quarto ist ein Markdown-basiertes Dokumenten-Format, mit dem Dokumente direkt in RStudio erstellt werden und Ergebnisse, Tabellen und Abbildungen eingebunden werden können. Dieses Skript hier wurde auch in quarto erstellt.
Dabei ist neben der direkten Einbindung von Auswertungen in das Dokument der große Vorteil, dass in verschiedene Ausgabeformate gerendert werden kann. Zum Beispiel können Dokumente parallel in ein Word-Dokument und ein tex-File exportiert werden.
In RStudio kann über File -> New File -> Quarto Document ein neues Dokument erstellt werden. Daraufhin öffnet sich ein Dialog, in dem Einstellungen für das Dokument getroffen werden.
Die Felder können erstmal ruhig so gelassen werden wie sie sind, alle Einstellungen lassen sich auch im Nachhinein anpassen.
Das neu erstellte Dokument wird (ab RStudio 1.4) als Standard im visuellen Editor geöffnet.
Quarto-Dokumente basieren auf zwei Teilen, die in einem file oder getrennt voneinander existieren können. Der erste Teil ist der sogenannte YAML-Header (1 in Abbildung 8.2), der die Parameter zum Rendern des Dokuments definiert - der zweite Teil ist das eigentliche Dokument(2).
Im neu erstellten file erkennen wir den YAML-Header durch die Eingrenzung aus je drei Bindestrichen. Nach der Erstellung sind hier schon der Titel des Dokuments “Untitled” und die Nutzung des visuellen Editors festgelegt.
Der Rest des Files ist ein Markdown-Dokument in dem mit markdown-Formatierung Fließtext geschrieben werden kann. Seit Einführung des visuellen Editors ist aber selbst diese Syntax nicht mehr nötig, Text kann wie aus anderen Verarbeitungsprogrammen bekannt mit den Bedienfeldern(3) formatiert werden. Durch Drücken der Source-Schaltfläche (4) kann aber auch immer noch in den Source-Editor zurückgekehrt werden.
Wie schon angedeutet ist quarto kein WYSIWYG1-Editor, sondern erfordert das Rendern von Dokumenten. Dazu kann auf “Render”(5) geklickt oder Strg + Shift + K als Shortcut genutzt werden. Auf diesen Befehl hin wird neben dem qmd-file ein Output generiert, in dem die formatierte Version zu finden ist. Beim ersten Rendern öffnet sich ein Dialog, in dem noch ein file-Name und Speicherort angegeben wird.
1 What you see is what you get
Code-chunks
Der große Vorteil quartos ist es, dass wir Code-chunks im Dokument anlegen können, deren Output direkt in das gerenderte Ergebnis eingebunden wird.
Dazu kann mit der “Insert new code chunk”-Schaltfläche (1 in Abbildung 8.3) oben rechts oder Strg + Alt + I ein neuer Chunk eingefügt werden, der an die Cursor-Stelle im Dokument eingefügt wird (2).
In der ersten Zeile des neuen Chunks steht die Sprache. In den Chunk kann dann wie in ein R-Skript Code eingefügt werden.
In Abbildung 8.4 ist das neue file mit dem Code für die Grafik aus Grammar of Graphics und ggplot2 eingefügt.
Der erste Chunk (1) ist dabei nur dafür da um Pakete und die Daten zu laden und ein theme zu setzen. Im zweiten Chunk (2) wird die Grafik erstellt.
Wie in (3) und (4) zu sehen ist, kann zwischen den Chunks einfach Text eingefügt werden.
Die Chunks können dabei wie ein ganz normales R-Skript genutzt werden und der Code an der Zeile des Cursors kann mit Strg + Enter ausgeführt werden. Der Output erscheint dabei unter dem Chunk, kann mit Hilfe der Einstellungen aber auch in die Konsole verschoben werden.
Damit haben wir die Basics die wir brauchen.
YAML-Header
Um das Ergebnis des Renderns anzupassen können wir den YAML-Header setzen.
Für dieses Skript konzentrieren wir uns auf Output im docx-Format, Quarto bietet aber wesentlich mehr Optionen. Die Doku für alle unterstützten Header-Optionen für docx findet sich hier.
Für uns sind erstmal die folgenden Parameter wichtig:
format: docx # setzt das Format des Outputs
fig-width: 6.56 # setzt 6.56 Zoll als Standard-Breite für alle Plot-Outputs
fig-dpi: 300 # setzt alle plots auf 300 dpiNach Klick auf “Render” kann ich neben dem erstellten qmd-file das in Abbildung 8.5 abgebildete Dokument finden.
Der Output der Chunks wurde also erfolgreich in das Dokument übergeben, ich brauche aber die ganzen messages nicht.
Um diese zu unterdrücken kann ich den YAML-Header einfach um den folgenden Teil ergänzen:
execute:
warning: false
message: falseExecute im YAML-Header setzt dabei Ausführungsstandards für alle Code-Chunks im Dokument. warning: false unterdrückt alle Warnungen, message: false alle Nachrichten von Paketen, etc. im Output.
Was zu folgendem Output führt:
Schon viel besser, für einen Bericht stört aber noch der Code zwischen den Outputs. Um das Rausschreiben der Chunks zu unterdrücken ergänzen wir nur noch echo: false um bei folgendem vollständigen Header zu enden:
title: "Methoden"
editor: visual
format: docx
fig-width: 6.56
fig-dpi: 300
execute:
warning: false
message: false
echo: falseUnd schon ist das Ergebnis nicht mehr allzu schlecht:
Code-Chunk-Optionen
Die letzten drei Parameter waren Beispiele für chunk-Optionen, die das Verhalten von Chunks anpassen. Das kann entweder global im YAML-Header unter execute oder lokal pro Chunk gesetzt werden.
Auf der quarto-Seite gibt es einen Überblick über alle Optionen, wir konzentrieren uns aber erstmal auf einen kleinen Teil zur Beschriftung von Grafiken.
Um eine Grafik zu beschriften und im Text referenzierbar zu machen, müssen wir zwei Optionen für den Chunk setzten: label und fig-cap. In Abbildung 8.7 ist ein Beispiel wie das aussehen könnte. Die Chunk-Optionen werden dabei immer durch ein so genanntes “pipe-comment” eingeleitet.
Im text können wir die Grafik dann mit @fig-scatter referenzieren. Das label für Grafiken muss dabei durch “fig-” eingeleitet und referenziert werden, sonst schlägt die Formatierung fehl.
Der Output des so angepassten Skripts ist in Abbildung 8.8 zu sehen.
In dem Beispiel ist außerdem ein weiterer Vorteil von Quarto zu sehen: Inline Code-Chunks
Inline Code-Chunks
Im Fließtext kann mit der folgenden Syntax auf R zugegriffen und Output generiert werden:
`r <some code>`Wozu ist das nützlich? Wir können so einfach statistische Kennwerte ohne sie kopieren zu müssen in den Text einfließen lassen! Und jedes mal wenn das Ergebnis erstellt wird, werden die Werte neu berechnet. So kann keine Aktualisierung vergessen werden.
Wir könnten unserem Beispiel-File so beispielsweise eine Stichprobenbeschreibung hinzufügen, wie in Abbildung 8.9 zu sehen ist.
Die Ergebnisse im docx können in Abbildung 8.10 gesehen werden.
Das hier gezeigte Beispiel ist auch im Repo des Skripts zugänglich. Außerdem sind dort alle für die Erstellung dieses Skripts nötigen files zu finden.
Aufgabe
Übertragen Sie Ihre Ergebnisse aus den Aufgaben zu
tidymodelsin einquarto-Dokument.Beschriften Sie alle Grafiken.
Rendern Sie das Dokument als
docx.
Zusammenarbeit
Der größte Nachteil an Quarto ist der etwas umständlichere Workflow beim Kommentieren und Zusammenarbeiten als das in Word möglich ist.
Die Dokumente können zwar immer in word gerendert und dann ausgetauscht werden, etwaige Anmerkungen können aber nicht direkt in Quarto eingepflegt werden.
Unter diesem Link findet sich aber eine Anleitung, wie man die Zusammenarbeit über git ermöglichen kann.
Außerdem ist dort auch eine Anleitung zu finden, wie sich im Source-Editor mit quarto zitieren lässt. Für das Zitieren im allgemeinen ist der quarto-Guide zu diesem Thema ein guter Anlaufpunkt.