20  quarto

quarto ermöglicht es, R-Code, -Output und -Diagramme, sowie Formeln und externe Quellen (z.B. Bilder aus dem Internet) in ansprechenden Dokumenten (z.B. Webseite, Word, Powerpoint, PDF) zu exportieren. Es ist sehr gut dafür geeignet, die eigenen statistischen Auswertungen und Ergebnisse für Endanwender (z.b. Auftragsgeber oder Dozenten) darzustellen.

quarto ist der Nachfolger von RMarkdown und wurde 2022 veröffentlicht. Basierend auf den Erkenntnissen der letzten 10 Jahre mit RMarkdown wurde es von Grund auf neu aufgebaut, um mehr Sprachen und Umgebungen zu unterstützen.

quarto unterstützt die Publikationsformate

in den Ausgabeformaten HTML, PDF, ePub und Office.

Dieses Buch wurde jahrelang mit RMarkdown (bookdown) erzeugt und ist im September 2022 auf quarto umgezogen.


Mehr Infos erhalten Sie unter https://www.quarto.org.

20.1 Installation

In einer aktuellen Installation von RStudio ist quarto bereits enthalten.

Unter Linux muss zusätzlich das Paket quarto-cli installiert werden. Für Ubuntu steht ein .deb-Paket unter https://quarto.org/docs/get-started/ bereit, unter Archlinux lautet der Befehl:

yay -S quarto-cli-bin

20.2 Dokument erstellen

Wir erstellen in unserem Projekt ErsteSchritte nun das erste Markdown-Dokument. Klicken Sie hierzu wieder oben im Scriptfenster auf das grüne + Symbol und wählen Sie Quarto Document, siehe Abbildung 20.1

Abb. 20.1: neues Quarto Dokument

Falls Sie dies zum ersten Mal tun, schlägt RStudio die notwendigen Zusatzpaket zur Installation vor. Die Installation dauert ein paar Minuten, und Sie können den Prozess unten im Konsolfenster verfolgen.

Es öffnet sich ein neues Fenster (Abbildung 20.2). Wir erstellen hier ein Dokument, Sie sehen aber schon, dass quarto weitere Formate (z.B. Präsentationen) ebenfalls unterstützt.

Abb. 20.2: neues HTML Dokument

Tragen Sie den Titel des Dokumentes sowie den Autoren ein. Wir belassen in diesem Beispiel die Default Output Option auf HTML.

Es wird nun eine Standardvorlage des Dokumentes erzeugt (Abbildung 20.3). Bevor wir uns dem Inhalt zuwenden speichern wir das Dokument zunächst ab. Klicken Sie hierzu auf das Diskettensymbol (Mauszeiger in Abbildung 20.3) oder drücken Sie die Tastenkombination [STRG] + [S]. Geben Sie Ihrem Dokument einen Dateinamen mit der Endung .qmd (für quarto-Markdown). Ich habe meine Datei Mein-quarto-Dokument.qmd genannt.

Abb. 20.3: speichern über Diskettensymbol

Die Datei ist nun ebenfalls im Dateiverzeichnis zu sehen (Abbildung 20.4) und kann von dort aus geöffnet werden.

Abb. 20.4: quarto-Dokument im Arbeitsverzeichnis

Über dem Scriptfenster befindet sich der Render-Knopf (Abbildung 20.5, Mauszeiger).

Abb. 20.5: Render-Knopf

Wenn Sie hier klicken, oder die Tastenkombination [STRG] + [SHIFT] + [K] benutzen, wird aus Ihrem quarto-Markdown die gewünschte Ausgabedatei (in diesem Beispiel html, also eine Webseite) erzeugt und im Arbeitsverzeichnis gespeichert.

Da die Standardvorlage alle wichtigen Dinge enthält können wir direkt auf den Render-Knopf klicken. Das quarto-Dokument wird nun “übersetzt”, und Sie können den Prozess im Konsolenfenster verfolgen (Abbildung 20.6).

Abb. 20.6: Render-Prozess

Ist dieser Schritt erfolgreich, öffnet sich ein neues Fenster mit dem Endresultat (Abbildung 20.7).

Abb. 20.7: fertiges quarto Dokument

In unserem Arbeitsverzeichnis sehen wir ebenfalls die soeben erzeugte Ausgabedatei, in Abbildung 20.8 ist das Mein-quarto-Dokument.html.

Abb. 20.8: fertige HTML-Datei

20.3 Editor-Ansicht

Das quarto-Dokument startet im “visuellen Editor”, der so ähnlich funktioniert wie Word oder LibreOffice. So können Sie Ihren Text “wie gewohnt” gestalten. Sie haben zudem oben eine Menüzeile, mit der Sie die Schriftart wechseln, externe Bilder einbinden oder Tabellen erzeugen können.

Auf der linken Seite können Sie zwischen dem visuellen Editor und der Code-Ansicht wechseln.

Source-Editor

Visueller Editor

Denken Sie daran, in die klassische Code-Ansicht zurück zu wechseln, bevor Sie Markdown-Code kopieren und einfügen.

Dies ist ein häufiger Anfgängerfehler, und der visuelle Editor kann mit dem Code nichts anfangen.

20.4 Dokumentenaufbau

Schauen wir uns unsere eben erzeugte Markdowndatei noch einmal an. Wechseln Sie hierzu in die Code-Ansicht.

--- 
title: "Mein quarto Bericht" 
author: "Jörg große Schlarmann" 
format: html
editor: visual
---

Dies ist die Kopfzeile des Dokuments, die im yaml-Format angegeben ist (so genannter yaml-Header). Wir können hier den Titel, Autor und das Datum ändern. Alle Parameter des Headers finden Sie unter https://quarto.org/docs/reference/formats/html.html

Unter den drei Strichen --- beginnen wir unser eigentliches Dokument. Schreiben Sie folgende Zeilen in Ihr Dokument:

---
title: "Mein quarto Bericht" 
author: "Jörg große Schlarmann" 
date: "01 09 2022"
format: html
editor: visual
---

# Überschrift

Willkommen zu meinem quarto-Markdown-Dokument

- dies ist ein Punkt

- dies ein weiterer

1. erstens

2. zweitens

3. drittens

## Unter-Überschrift

Dies ist **fett**, dies *kursiv*, dies ~~durchgestrichen~~.

Drücken Sie den Render-Knopf und erzeugen so einen Testoutput.

Abb. 20.9: fertig gerendertes Testdokument

Das Zeichen # steht für Überschriften und deren Hierarchie. Die Anzahl der # legt die Überschriftenhierarchie fest. Aus den Spiegelstrichen ist eine Liste geworden, die Zahlen wurden in eine nummerierte Aufzählungsliste umgewandelt.

20.5 Markdown-Syntax

Die Syntax von Markdown ist recht leicht, die folgenden Beispiele wurden aus dem Quarto-Guide hierhin übernommen:

20.5.1 Textformat

Markdown Syntax Output
*italics* and **bold**
italics and bold
superscript^2^ / subscript~2~
superscript2 / subscript2
~~strikethrough~~
strikethrough
`verbatim code`
verbatim code

20.5.2 Überschriften

Markdown Syntax Output
# Header 1

21 Header 1

## Header 2

21.1 Header 2

### Header 3

21.1.1 Header 3

#### Header 4

21.1.1.1 Header 4

##### Header 5
21.1.1.1.1 Header 5
###### Header 6
21.1.1.1.1.1 Header 6

21.1.3 Listen

Markdown Syntax Output
* unordered list
    + sub-item 1
    + sub-item 2
        - sub-sub-item 1
  • unordered list

    • sub-item 1

    • sub-item 2

      • sub-sub-item 1
*   item 2

    Continued (indent 4 spaces)
  • item 2

    Continued (indent 4 spaces)

1. nummerierte Liste
2. item 2
    i) sub-item 1
         A.  sub-sub-item 1
  1. nummerierte Liste

  2. item 2

    1. sub-item 1

      1. sub-sub-item 1
(@)  Eine Liste deren Nummerierung

nach einer Unterbrechung

(@)  fortgeführt wird
  1. Eine Liste deren Nummerierung

nach einer Unterbrechung

  1. fortgeführt wird
Term
: Definition
Term

Definition

21.1.4 Tabellen

In Markdown können sehr leicht Tabellen erzeugt werden. Versuchen Sie diesen Code aus (vorher vom visuellen Editor zurückwechseln!), und beachten Sie, wie “gut lesbar” und “leicht zu merken” das ist.

21.1.4.1 Markdown Syntax

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

21.1.4.2 Output

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

21.1.5 Gleichungen

Mit $ können In-Text-Formeln erzeugt werden, mit $$ schließt man Matheumgebungen ein:

Markdown Syntax Output
inline math: $E = mc^{2}$
inline math: \(E=mc^{2}\)
display math:

$$E = mc^{2}$$
display math:
\[E = mc^{2}\]

21.2 R-Code integrieren

Kommen wir nun zum eigentlichen Kernpunkt: der Darstellung von R-Code und -Output.

Hierfür muss im Markdowndokument der Bereich für den R-Code festgelegt werden. Dies erfolgt über die Zeichenkette ``` , die den Codebereicht einschließt.

```{r}
# hier steht der R-Code
```

Die Anführungsstriche grenzen den Codebereich ein. Dieser wird Chunk genannt. Das {r} bedeutet, dass R-Code verwendet wird.

Achten Sie auf die korrekten Anführungszeichen!

Achten Sie darauf, die korrekten ``` zu verwenden, und nicht etwa ''' oder ´´´. Dies ist ein häufiger Anfängerfehler.

In RStudio können Sie einfach die Tastenkombination [STRG] + [ALT] + [i] drücken, oder im Scriptfenster oben auf das grüne c klicken, siehe Mauszeiger in Abbildung 21.1.

Abb. 21.1: einen neuen Chunk erstellen

Beides fügt einen neuen Chunk (Codeblock) ein.

Die Chunks werden im Editorfenster farblich hervorgehoben.

Tragen Sie folgenden Code in den Chunk ein:

load(url("https://www.produnis.de/R/pf8.RData"))
plot(pf8$Alter, pf8$Gewicht)

Wenn Sie den Render-Knopf drücken, wird der load()-Befehl im Dokument angezeigt und in der Konsole ausgeführt. Das neu gerenderte HTML-Dokument öffnet sich automatisch.

Abb. 21.2: Dokument mit Plot

Sie haben auch die Möglichkeit, den Code auszuführen und sich das Ergebnis anzeigen zu lassen, ohne das komplette Dokument zu Rendern . Klicken Sie dazu rechts auf das grüne Dreieck (Abbildung 21.3).

Abb. 21.3: Chunk-Code ausführen

In diesem Beispiel wird der Plot nun direkt im Markdownfenster angezeigt (Abbildung 21.4). Dies ist wirklich hilfreich beim Erstellen des Dokuments, denn Sie müssen nicht immer erst das gesamte Dokument rendern oder überhaupt geöffnet haben, um zu sehen, was R an dieser Stelle ausgeben würde.

Abb. 21.4: Der Chunk-Output wird bereits im Editor angezeigt

Über das Symbol links daneben (Abbildung 21.5, siehe Mauszeiger) lassen sich “alle Chunks bis hier hin” ausführen.

Abb. 21.5: alle Chunks oberhalb ausführen

Dies ist zum Beispiel hilfreich, wenn in den vorherigen Chunks Objekte oder Variablen erzeugt wurden, auf die nun zugegriffen werden soll.

21.2.1 Chunk-Optionen

Den Chunks können Parameter übergeben, um ihr Verhalten zu steuern. Dies erfolgt über die Zeichenfolge #| direkt am Zeilenanfang.

```{r}
#| label: fig-testplot # zum verlinken der Plots
#| fig-cap: "Testplot" # Plotunterschrift
#| echo: true          # R-Befehle anzeigen      
#| output: true        # R-Output anzeigen
#| warning: false      # Warnung unterdrücken
#| include: true       # Chunk anzeigen
#| eval: true          # Code ausführen
load(url("https://www.produnis.de/R/pf8.RData"))
plot(pf8$Alter, pf8$Gewicht)
```

Abb. 21.6: Testplot

Der Plot ist über den Referenzierer @fig-testplot ansprechbar. Dieser wird beim rendern umgewandelt in \(\rightarrow\)Abbildung 21.6”.

Die Standard-Parameter lauten:

  • label - gibt dem Chunk einen Namen. Dies ist beim Debugging sehr hilfreich. Soll auf die Plots des Chunks referenziert werden, muss das Label zwingend mit fig- anfangen.
  • fig-cap - gibt den Plottitel an.
  • echo - gibt an, ob die Befehle des Chunks im Dokument angezeigt werden sollen (true/false).
  • output - gibt an, ob die R-Ausgaben im Dokument angezeigt werden sollen (true/false).
  • warning - gibt an, ob die Warnungen, die möglicherweise beim Ausführen des Codes ausgegeben werden, im Dokument angezeigt werden sollen (true/false).
  • include - gibt an, ob der Chunk (Befehle und Ausgabe) im Dokument angezeigt werden soll (true/false).
  • eval - gibt an, ob der Chunk ausgeführt (true) werden, oder nur der Chunkinhalt angezeigt werden soll (false).

21.3 PDF-Dokumente erzeugen

Da PDF-Dokumente von quarto intern mittels \(\LaTeX\) erzeugt werden, müssen Sie auf Ihrem PC eine \(\LaTeX\) Distribution installiert haben.

Falls dies nicht der Fall ist, können Sie TinyTeX mit folgendem Behfehl im RStudio-Terminal installieren:

quarto install tool tinytex

Mit dieser Methode installiert quarto alle weiteren Pakete automatisch, sofern diese benötigt werden. Sollten Sie bereits eine \(\LaTeX\)-Distribution installiert haben, müssen Sie das Paket fontawesome installieren, damit alles funktioniert.

21.4 quarto-Dokumentation

Die Webseite von quarto bietet umfangreiche Anleitungs- und Referenzierungsdokumente an.

Siehe auch Kapitel 35.