Relation entre R Markdown, Knitr, Pandoc et Bookdown


90

Quelle est la relation entre les fonctionnalités de R Markdown, Knitr, Pandoc et Bookdown?

Plus précisément, quelle est la «division du travail» entre ces packages dans la conversion de documents de balisage avec du code R intégré (par exemple .Rnwou .Rmd) en sorties finales (par exemple .pdfou .html)? Et si Knitr est utilisé pour traiter RMarkdown, que fait le rmarkdownpackage et en quoi est-il différent du markdown package?

Réponses:


135

Pandoc

Pandoc est un convertisseur de documents. Il peut convertir un certain nombre de formats de balisage différents vers de nombreux autres formats, tels que .doc, .pdfetc.

Pandoc est un outil de ligne de commande sans interface graphique. Il s'agit d'un logiciel indépendant, distinct de R. Cependant, il est fourni avec R Studio car il en rmarkdowndépend pour la conversion de documents.

Pandoc convertit non seulement les documents, mais ajoute également des fonctionnalités en plus du langage de démarquage de base pour lui permettre de prendre en charge des sorties plus complexes.

R Markdown

R Markdown est basé sur le démarquage:

Markdown (langage de balisage)

Markdown est un langage de balisage léger avec une syntaxe de formatage de texte brut conçu pour pouvoir être converti en HTML et dans de nombreux autres formats. Un fichier markdown est un fichier texte brut auquel l'extension est généralement attribuée .md.

Comme d'autres langages de balisage comme HTML et Latex, il est complètement indépendant de R.

Il n'y a pas de norme Markdown clairement définie. Cela a conduit à une fragmentation, car différents fournisseurs écrivent leurs propres variantes du langage pour corriger les failles ou ajouter des fonctionnalités manquantes.

Markdown (package R)

markdownest un package R qui convertit les .Rmdfichiers en HTML. C'est le prédécesseur de rmarkdown, qui offre beaucoup plus de fonctionnalités. Son utilisation n'est plus recommandée.

R Markdown (langage de balisage)

R Markdown est une extension de la syntaxe Markdown. Les fichiers R Markdown sont des fichiers texte brut qui ont généralement l'extension de fichier .Rmd. Ils sont écrits en utilisant une extension de la syntaxe de démarque qui permet au code R d'y être incorporé d'une manière qui peut être exécutée ultérieurement.

Comme ils sont censés être traités par le rmarkdownpackage, il est possible d'utiliser la syntaxe de démarquage Pandoc dans le cadre d'un fichier de démarquage R. Il s'agit d'une extension de la syntaxe de démarque originale qui fournit des fonctionnalités supplémentaires telles que HTML / Latex brut et les tableaux.

R Markdown (paquet)

Le package R rmarkdownest une bibliothèque qui traite et convertit les .Rmdfichiers dans un certain nombre de formats différents.

La fonction de base est ce rmarkdown::renderqui se dresse sur les épaules de pandoc . Cette fonction rend le fichier d'entrée au format de sortie spécifié à l'aide de pandoc. Si l'entrée nécessite un tricot, elle knitr::knitest appelée avant pandoc.

Le but du package RMarkdown est simplement de fournir des valeurs par défaut raisonnablement bonnes et une interface conviviale pour personnaliser les options Pandoc. .

Les métadonnées YAML vues en haut des fichiers RMarkdown sont spécifiquement destinées à transmettre des options rmarkdown::renderpour guider le processus de construction.

Notez que RMarkdown ne traite que de la syntaxe de démarque. Si vous souhaitez convertir un fichier .Rhtmlou un .Rnwfichier, vous devez utiliser les fonctions pratiques intégrées Knitr, telles que knitr::knit2htmletknitr:knit2pdf

Knitr

Knitr prend un document en texte brut avec du code incorporé, exécute le code et «transforme» les résultats dans le document.

Par exemple, il convertit

La fonction principale est knitr::knitet par défaut, elle examinera le document d'entrée et essaiera de deviner de quel type il s'agit - Rnw, Rmd, etc.

Cette fonction principale remplit trois rôles: - Un analyseur source, qui examine le document d'entrée et détecte quelles parties sont du code que l'utilisateur souhaite évaluer. - Un évaluateur de code, qui évalue ce code - Un moteur de rendu de sortie, qui écrit les résultats de l'évaluation dans le document dans un format interprétable par le type de sortie brute. Par exemple, si le fichier d'entrée est un .Rmd, le rendu de sortie marque la sortie de l'évaluation du code au .mdformat.

Conversion entre les formats de document

Knitr ne pas convertir entre les formats de documents - tels que la conversion d' un .mden .html. Cependant, il fournit des fonctions pratiques pour vous aider à utiliser d'autres bibliothèques pour ce faire. Si vous utilisez le rmarkdownpackage, vous devez ignorer cette fonctionnalité car elle a été remplacée par rmarkdown::render.

Un exemple est knitr:knit2pdfce qui va: «Tricoter le document d'entrée Rnw ou Rrst, et compiler au format PDF en utilisant texi2pdf ou rst2pdf».

Une source potentielle de confusion est knitr::knit2html, qui "est une fonction pratique pour tricoter la source de démarquage d'entrée et appeler markdown::markdownToHTMLpour convertir le résultat en HTML." Il s'agit désormais d'une fonctionnalité héritée car le markdownpackage a été remplacé par le rmarkdownpackage. Voir cette note .

Bookdown

Le package bookdown est construit sur R Markdown et hérite de la simplicité de la syntaxe Markdown, ainsi que de la possibilité de plusieurs types de formats de sortie (PDF / HTML / Word /…).

Il offre des fonctionnalités telles que la sortie HTML de plusieurs pages, la numérotation et les références croisées des figures / tableaux / sections / équations, l'insertion de parties / annexes et l'importation du style GitBook ( https://www.gitbook.com ) pour créer un HTML élégant et attrayant pages de livre.


2
J'ai trouvé cela très déroutant, alors j'ai fait de mon mieux ici. Veuillez modifier ou ajouter une réponse différente si quelque chose ne va pas ...
RobinL

6
un aspect que je trouve déroutant est la documentation des paramètres passés à chaque étape de la chaîne d'outils. Il n'y a presque pas d'aide interactive (comme l' knitr_optsauto-complétion ) et il faut deviner quels paramètres doivent être appelés dans les en-têtes yaml, ou via (j'oublie toujours comment cela s'appelle), ou via des arguments pandoc personnalisés, ou via des fichiers yam supplémentaires, ou un personnalisé modèle pandoc ... Cela semble parfois un peu la jungle, surtout lorsque vous ajoutez LaTeX à la chaîne.
baptiste

3
@baptiste Je suis tout à fait d'accord. Et c'est exactement la raison pour laquelle je préfère les documents RNW avec LaTeX nu. Pas d' pandocétape intermédiaire , moins de magie, moins de confusion. Juste la courbe d'apprentissage LaTeX, certes raide. À mon avis, Rmarkdown est génial lorsque vous êtes satisfait des éléments simples par défaut. Mais dès qu'il faut le peaufiner, la complexité augmente rapidement.
CL.

3
C'est la meilleure explication que j'ai trouvée de tout cela. C'est très déroutant pour les débutants ou même ceux qui ont des années d'expérience dans le R et le latex séparément comme moi. Excellent poste.
StatsStudent

2
@StatsStudent Je pense qu'une version précédente de la feuille de triche rstudio rmarkdown avait un diagramme qui était assez utile pour comprendre les différentes étapes de création de sortie à partir de rmarkdown. Peut-être qu'une réponse ici pourrait faire avec un diagramme?
Mark Neal
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.