Beziehung zwischen R Markdown, Knitr, Pandoc und Bookdown

90

Welche Beziehung besteht zwischen der Funktionalität von R Markdown, Knitr, Pandoc und Bookdown?

Was ist konkret die Arbeitsteilung zwischen diesen Paketen bei der Konvertierung von Markup-Dokumenten mit eingebettetem R-Code (z. B. .Rnwoder .Rmd) in endgültige Ausgaben (z. B. .pdfoder .html)? Und wenn Knitr zur Verarbeitung von RMarkdown verwendet wird, was macht das rmarkdownPaket und wie unterscheidet es sich von dem markdown package?

RobinL
quelle

Antworten:

133

Pandoc

Pandoc ist ein Dokumentenkonverter. Es kann aus einer Anzahl verschiedener Markup - Formate für viele andere Formate wie zu umwandeln .doc, .pdfusw.

Pandoc ist ein Befehlszeilenprogramm ohne GUI. Es handelt sich um eine unabhängige Software, die von R getrennt ist. Sie wird jedoch mit R Studio rmarkdowngeliefert, da sie für die Dokumentkonvertierung verwendet wird.

Pandoc konvertiert nicht nur Dokumente, sondern fügt zusätzlich zur Basis-Markdown-Sprache Funktionen hinzu, um komplexere Ausgaben zu unterstützen.

R Abschlag

R Markdown basiert auf Markdown:

Markdown (Auszeichnungssprache)

Markdown ist eine einfache Markup-Sprache mit einer Syntax zur Formatierung von Klartext, die so konzipiert ist, dass sie in HTML und viele andere Formate konvertiert werden kann. Eine Markdown-Datei ist eine Nur-Text-Datei, die normalerweise die Erweiterung erhält .md.

Wie andere Markup-Sprachen wie HTML und Latex ist es völlig unabhängig von R.

Es gibt keinen klar definierten Markdown-Standard. Dies hat zu einer Fragmentierung geführt, da verschiedene Anbieter ihre eigenen Sprachvarianten schreiben, um Fehler zu korrigieren oder fehlende Funktionen hinzuzufügen.

Abschlag (R-Paket)

markdownist ein R-Paket, das .RmdDateien in HTML konvertiert . Es ist der Vorgänger von rmarkdown, der viel mehr Funktionalität bietet. Es wird nicht mehr zur Verwendung empfohlen.

R Markdown (Markup-Sprache)

R Markdown ist eine Erweiterung der Markdown-Syntax. R Markdown-Dateien sind Nur-Text-Dateien, die normalerweise die Dateierweiterung haben .Rmd. Sie werden mit einer Erweiterung der Markdown-Syntax geschrieben, mit der R-Code auf eine Weise in sie eingebettet werden kann, die später ausgeführt werden kann.

Da erwartet wird, dass sie vom rmarkdownPaket verarbeitet werden , ist es möglich, die Pandoc-Markdown-Syntax als Teil einer R-Markdown-Datei zu verwenden. Dies ist eine Erweiterung der ursprünglichen Markdown-Syntax, die zusätzliche Funktionen wie HTML / Latex und Tabellen bietet.

R Markdown (Paket)

Das R-Paket rmarkdownist eine Bibliothek, die .RmdDateien verarbeitet und in verschiedene Formate konvertiert .

Die Kernfunktion ist, rmarkdown::renderdie auf den Schultern des Pandoc steht . Diese Funktion rendert die Eingabedatei mit pandoc in das angegebene Ausgabeformat. Wenn die Eingabe knitr::knitgestrickt werden muss, wird vor pandoc aufgerufen.

Das Ziel des RMarkdown-Pakets besteht einfach darin, einigermaßen gute Standardeinstellungen und eine R-freundliche Oberfläche zum Anpassen der Pandoc-Optionen bereitzustellen. .

Die YAML-Metadaten, die oben in RMarkdown-Dateien angezeigt werden, dienen speziell dazu, Optionen zu übergeben rmarkdown::render, um den Erstellungsprozess zu steuern .

Beachten Sie, dass RMarkdown nur die Markdown-Syntax behandelt. Wenn Sie eine .Rhtmloder eine .RnwDatei konvertieren möchten , sollten Sie die integrierten Komfortfunktionen Knitrwie knitr::knit2htmlund verwendenknitr:knit2pdf

Knitr

Knitr nimmt ein Nur-Text-Dokument mit eingebettetem Code, führt den Code aus und "strickt" die Ergebnisse wieder in das Dokument.

Zum Beispiel konvertiert es

Die Kernfunktion ist knitr::knitund standardmäßig wird das Eingabedokument angezeigt und versucht zu erraten, um welchen Typ es sich handelt - Rnw, Rmd usw.

Diese Kernfunktion erfüllt drei Rollen: - Ein Quellparser, der das Eingabedokument betrachtet und erkennt, welche Teile Code sind, den der Benutzer auswerten möchte. - Ein Code-Evaluator, der diesen Code auswertet. - Ein Ausgaberender, der die Ergebnisse der Auswertung in einem Format in das Dokument zurückschreibt, das vom Rohausgabetyp interpretiert werden kann. Wenn es sich bei der Eingabedatei beispielsweise um eine handelt .Rmd, markiert das Ausgabe-Rendering die Ausgabe der Code-Auswertung im .mdFormat.

Konvertieren zwischen Dokumentformaten

Knitr konvertiert nicht zwischen Dokumentformaten, z. B. das Konvertieren von a .mdin a .html. Es bietet jedoch einige praktische Funktionen, mit denen Sie andere Bibliotheken verwenden können. Wenn Sie das rmarkdownPaket verwenden, sollten Sie diese Funktionalität ignorieren, da sie von ersetzt wurde rmarkdown::render.

Ein Beispiel ist knitr:knit2pdf: 'Stricken Sie das eingegebene Rnw- oder Rrst-Dokument und kompilieren Sie es mit texi2pdf oder rst2pdf in PDF'.

Eine mögliche Quelle der Verwirrung ist knitr::knit2html, dass "eine bequeme Funktion ist, um die Eingabe-Markdown-Quelle zu stricken und aufzurufen markdown::markdownToHTML, um das Ergebnis in HTML zu konvertieren." Dies ist jetzt eine Legacy-Funktionalität, da das markdownPaket vom rmarkdownPaket abgelöst wurde. Siehe diesen Hinweis .

Buchung

Das Bookdown-Paket basiert auf R Markdown und übernimmt die Einfachheit der Markdown-Syntax sowie die Möglichkeit mehrerer Arten von Ausgabeformaten (PDF / HTML / Word /…).

Es bietet Funktionen wie mehrseitige HTML-Ausgabe, Nummerierung und Querverweise von Abbildungen / Tabellen / Abschnitten / Gleichungen, Einfügen von Teilen / Anhängen und den Import des GitBook-Stils ( https://www.gitbook.com ), um elegantes und ansprechendes HTML zu erstellen Buchseiten.

RobinL
quelle
2
Ich fand das sehr verwirrend und habe hier mein Bestes gegeben. Bitte bearbeiten oder fügen Sie eine andere Antwort hinzu, wenn ich etwas falsch gemacht habe ...
RobinL
6
Ein Aspekt, den ich verwirrend finde, ist die Dokumentation der Parameter, die an jeden Schritt der Toolchain übergeben werden. Es gibt fast keine interaktive Hilfe (wie die automatische Vervollständigung) und man muss raten, welche Parameter in Yaml-Headern oder über knitr_opts(ich vergesse immer, wie es heißt) oder über benutzerdefinierte Pandoc-Argumente oder über zusätzliche Yam-Dateien oder eine benutzerdefinierte Hilfe aufgerufen werden sollen Pandoc-Vorlage ... Manchmal fühlt es sich wie ein Dschungel an, besonders wenn Sie LaTeX zur Kette hinzufügen.
Taufe
3
@baptiste Ich stimme vollkommen zu. Und genau aus diesem Grund bevorzuge ich RNW-Dokumente mit nacktem LaTeX. Kein Zwischenschritt pandoc, weniger Magie, weniger Verwirrung. Nur die zugegebenermaßen steile LaTeX-Lernkurve. Meiner Meinung nach ist Rmarkdown großartig, wenn Sie mit den einfachen Standardmaterialien zufrieden sind. Sobald Sie es jedoch anpassen müssen, steigt die Komplexität schnell an.
CL.
3
Dies ist die beste Erklärung, die ich für all das gefunden habe. Es ist sehr verwirrend für Anfänger oder sogar für diejenigen mit jahrelanger Erfahrung in R und Latex, wie ich. Ausgezeichnete Post.
StatsStudent
2
@StatsStudent Ich denke, eine frühere Version des rstudiodown-Spickzettel von rstudio hatte ein Diagramm, das ziemlich hilfreich war, um die verschiedenen Schritte beim Erstellen der Ausgabe von rmarkdown zu verstehen. Vielleicht könnte eine Antwort hier ein Diagramm vertragen?
Mark Neal