Shiny – Introduction à R Markdown – ecrire un livre d’aventure

Les documents interactifs constituent un nouveau moyen de créer des applications Shiny. Un document interactif est un R Markdown fichier qui contient des widgets et des sorties Shiny. Vous écrivez le rapport dans réduction, puis lancez-la en tant qu’application en cliquant sur un bouton.

Cet article vous montrera comment rédiger un rapport R. Markdown.

L'article d'accompagnement, Introduction aux documents interactifs, vous montrera comment transformer un rapport R Markdown en un document interactif avec des composants Shiny.

R Markdown

R Markdown est un format de fichier permettant de créer des documents dynamiques avec R. Un document R Markdown est écrit en markdown (format de texte brut facile à écrire) et contient des fragments de code R incorporé, comme le document ci-dessous.

---
Titre: R Réduction
sortie: html_document
---

Ce est un R Réduction document. Réduction est une simple mise en forme syntaxe lequel permet vous à auteur HTML, PDF, et MME Mot documents. Pour plus détails sur Comment à utilisation R Réduction, voir <http://rmarkdown.rstudio.com>.

Quand vous Cliquez sur la **Tricoter** bouton une document volonté être généré cette comprend tous les deux contenu comme bien comme la sortie de tout intégré R code morceaux dans la document. Vous pouvez intégrer un R code tronçon comme ce:

`` `r
résumé (voitures)
`` `

Vous pouvez également intégrer parcelles:

`` `r, echo = FALSE
terrain (voitures)
`` `

Remarque cette la `echo = FALSE` paramètre était ajoutée à la code tronçon à prévenir impression de la R code cette généré la terrain.

Les fichiers R Markdown sont conçus pour être utilisés avec le rmarkdown paquet. rmarkdown est installé avec l'IDE RStudio, mais vous pouvez acquérir votre propre copie de rmarkdown de github avec la commande

devtools:install_github("rmarkdown", "rstudio")

R Les fichiers Markdown constituent le code source de documents riches et reproductibles. Vous pouvez transformer un fichier R Markdown de deux manières.

  1. tricoter – Vous pouvez tricoter le fichier. le rmarkdown le paquet appellera le Knitr paquet. Knitr exécute chaque bloc de code R dans le document et ajoute les résultats du code au document situé à côté du bloc de code. Ce flux de travail permet de gagner du temps et facilite la création de rapports reproductibles.

    Considérez comment les auteurs incluent généralement des graphiques (ou des tableaux, ou des chiffres) dans un rapport. L'auteur crée le graphique, l'enregistre dans un fichier, puis le copie et le colle dans le rapport final. Ce processus repose sur le travail manuel. Si les données changent, l'auteur doit répéter tout le processus pour mettre à jour le graphique.

    Dans le paradigme R Markdown, chaque rapport contient le code dont il a besoin pour créer ses propres graphiques, tableaux, nombres, etc. L’auteur peut automatiquement mettre à jour le rapport en le tricotant à nouveau.

  2. convertir – Vous pouvez convertir le fichier. le rmarkdown forfait utilisera le pandoc programme pour transformer le fichier dans un nouveau format. Par exemple, vous pouvez convertir votre fichier .Rmd en un fichier HTML, PDF ou Microsoft Word. Vous pouvez même transformer le fichier en un diaporama HTML5 ou PDF. rmarkdown préservera le texte, les résultats de code et la mise en forme contenus dans votre fichier .Rmd d'origine.

    La conversion vous permet de réaliser votre travail initial dans Markdown, qui est très facile à utiliser. Vous pouvez inclure du code R à tricoter et partager votre document dans divers formats.

En pratique, les auteurs tricotent presque toujours et convertissent leurs documents en même temps. Dans cet article, je vais utiliser le terme rendre faire référence au processus en deux étapes de tricotage et de conversion d’un fichier R. Markdown.

Vous pouvez rendre manuellement un fichier R Markdown avec rmarkdown :: render (). Voici à quoi ressemble le document ci-dessus lorsqu'il est rendu sous forme de fichier HTML.

En pratique, vous n'avez pas besoin d'appeler rmarkdown :: render (). Vous pouvez utiliser un bouton dans l'IDE RStudio pour rendre votre rendu. R Markdown est fortement intégré à l'IDE RStudio.

Commencer

Pour créer un rapport R Markdown, ouvrez un fichier texte brut et enregistrez-le avec l’extension. .Rmd. Vous pouvez ouvrir un fichier texte brut dans votre éditeur de scripts en cliquant sur Fichier> Nouveau fichier> Fichier texte dans la barre d'outils RStudio.

Assurez-vous de sauvegarder le fichier avec l'extension .Rmd. RStudio IDE active plusieurs boutons utiles lorsque vous enregistrez le fichier avec l’extension .Rmd. Vous pouvez enregistrer votre fichier en cliquant sur Fichier> Enregistrer dans la barre d’outils RStudio.

Les rapports R Markdown s'appuient sur trois cadres

  1. démarque pour le texte formaté
  2. Knitr pour code R intégré
  3. YAML pour les paramètres de rendu

Les sections ci-dessous décrivent chaque cadre.

Markdown pour le texte formaté

Les fichiers .Rmd sont censés contenir du texte écrit en réduction. Markdown est un ensemble de conventions pour la mise en forme de texte brut. Vous pouvez utiliser le démarquage pour indiquer

  • texte en gras et en italique
  • des listes
  • en-têtes (par exemple, titres de section)
  • hyperliens
  • et beaucoup plus

Les conventions de Markdown sont très discrètes, ce qui facilite la lecture des fichiers Markdown. Le fichier ci-dessous utilise plusieurs des conventions de démarques les plus utiles.

# Dites bonjour à démarquer

Markdown est un format ** facile à utiliser ** pour la rédaction de rapports. Cela ressemble à ce que vous écrivez naturellement chaque fois que vous composez un courrier électronique. En fait, vous avez peut-être déjà utilisé markdown * sans vous en rendre compte *. Ces sites Web reposent tous sur le formatage à la baisse

* (Github) (www.github.com)
* (StackOverflow) (www.stackoverflow.com)
* (Reddit) (www.reddit.com)

Markdown est un facile à utiliser format pour la rédaction des rapports. Cela ressemble à ce que vous écrivez naturellement chaque fois que vous composez un courrier électronique. En fait, vous avez peut-être déjà utilisé le démarquage sans le savoir. Ces sites Web reposent tous sur le formatage à la baisse

Le fichier montre comment utiliser le démarquage pour indiquer:

  1. en-têtes – Placez un ou plusieurs hashtags au début d'une ligne qui sera un en-tête (ou un sous-en-tête). Par exemple, # Dites bonjour à démarquer. Un seul hashtag crée un en-tête de premier niveau. Deux hashtags, ##, crée un en-tête de deuxième niveau, etc.

  2. texte en italique et gras – Entourez le texte en italique avec des astérisques, comme ceci *sans le savoir*. Entourez le texte en gras avec deux astérisques, comme ceci **facile à utiliser**.

  3. des listes – Regroupez les lignes en points qui commencent par un astérisque. Laissez une ligne blanche avant la première puce, comme ceci:

        Ceci est une liste
    
      * objet 1
      * point 2
      * item 3
      
  4. hyperliens – Les liens surround avec des crochets, puis indiquez la cible du lien entre parenthèses, comme ceci (Github) (www.github.com).

    Vous pouvez en apprendre davantage sur les conventions de markdown dans le Référence Rapide Markdown guide, fourni avec l'IDE RStudio.

    Pour accéder au guide, ouvrez un .Maryland ou .Rmd fichier dans RStudio. Cliquez ensuite sur le point d'interrogation qui apparaît en haut du volet de scripts. Ensuite, sélectionnez «Référence rapide Markdown». RStudio ouvrira le Référence Rapide Markdown guide dans le volet Aide.

Le rendu

Pour transformer votre fichier de démarquage en un document HTML, PDF ou Word, cliquez sur l'icône «Tricoter» qui apparaît au-dessus de votre fichier dans l'éditeur de scripts. Un menu déroulant vous permettra de sélectionner le type de sortie que vous souhaitez.

Lorsque vous cliquez sur le bouton, rmarkdown dupliquera votre texte dans le nouveau format de fichier. rmarkdown utilisera les instructions de formatage que vous avez fournies avec la syntaxe Markdown.

Une fois le fichier rendu, RStudio vous montrera un aperçu de la nouvelle sortie et enregistrera le fichier de sortie dans votre répertoire de travail.

Voici à quoi ressemblerait le script de démarque ci-dessus dans chaque format de sortie.

Remarque: RStudio ne crée pas de documents PDF et Word à partir de rien. Une distribution de Latex doit être installée sur votre ordinateur pour créer des PDF et Microsoft Word (ou un programme similaire) installé pour créer des fichiers Word.

knitr pour code R intégré

le Knitr package étend la syntaxe de base de markdown pour inclure des fragments de code exécutable R.

Lorsque vous rendez le rapport, Knitr exécutera le code et ajoutera les résultats au fichier de sortie. Vous pouvez faire en sorte que la sortie affiche uniquement le code, uniquement les résultats, ou les deux.

Pour incorporer une partie du code R dans votre rapport, entourez le code de deux lignes contenant chacune trois backticks. Après la première série de backticks, incluez r, qui alerte Knitr que vous avez inclus un morceau de code R. Le résultat ressemblera à ceci

Ici's certains code
`` `r
dim (iris)
`` `

Lorsque vous rendez votre document, Knitr exécutera le code et ajoutera les résultats au bloc de code. Knitr fournira la mise en forme et la syntaxe en surbrillance à la fois au code et à ses résultats (le cas échéant).

En conséquence, l'extrait de démarquage ci-dessus ressemblera à ceci lors du rendu (au format HTML).

Omettre le résultats à partir de votre rapport final (sans exécuter le code), ajoutez l'argument eval = FALSE à l'intérieur des supports et après r. Cela placera une copie de votre code dans le rapport.

Omettre le code à partir du rapport final (tout en incluant les résultats), ajoutez l'argument echo = FALSE. Cela placera une copie des résultats dans votre rapport.

echo = FALSE est très pratique pour ajouter des tracés à un rapport, car vous ne voulez généralement pas voir le code qui génère le tracé.

écho et eval ne sont pas les seuls arguments que vous pouvez utiliser pour personnaliser les fragments de code. Vous pouvez en savoir plus sur le formatage de la sortie de fragments de code à la rmarkdown et Knitr sites Internet.

Code en ligne

Pour incorporer le code R dans une ligne de texte, entourez-le d'une paire de pics et de la lettre r, comme ça.

Deux plus deux équivaut à `r 2 + 2`.

Knitr remplacera le code en ligne par son résultat dans votre document final (le code en ligne est toujours remplacé par son résultat). Le résultat apparaîtra comme s'il faisait partie du texte original. Par exemple, l'extrait ci-dessus apparaîtra comme ceci:

YAML pour les paramètres de rendu

Vous pouvez utiliser un en-tête YAML pour contrôler comment rmarkdown rend votre fichier .Rmd. Un en-tête YAML est une section de valeur clé paires entourées --- marques, comme ci-dessous

---
Titre: "Sans titre"
auteur: "Garrett"
rendez-vous amoureux: "10 juillet 2014"
sortie: html_document
---

Certains en ligne R code, `r 2 + 2`.

le sortie: valeur détermine le type de sortie à convertir le fichier lorsque vous appelez rmarkdown :: render (). Remarque: vous n'avez pas besoin de spécifier sortie: si vous restituez votre fichier avec le bouton RStudio IDE.

sortie: reconnaît les valeurs suivantes:

  • html_document, qui créera une sortie HTML (par défaut)
  • document_pdf, qui créera une sortie PDF
  • document Word, ce qui créera une sortie Word

Si vous utilisez le bouton de tricotage IDE RStudio pour restituer votre fichier, la sélection effectuée dans l’interface graphique remplacera la sortie: réglage.

Diaporamas

Vous pouvez également utiliser le sortie: valeur pour rendre votre document sous forme de diaporama.

  • sortie: ioslides_presentation créera un diaporama ioslides (HTML5)
  • sortie: beamer_presentation créera un diaporama (PDF)

Remarque: le bouton Tricot dans l'EDI RStudio se mettra à jour pour afficher les options du diaporama lorsque vous incluez l'une des valeurs de sortie ci-dessus et enregistrez votre fichier .Rmd.

rmarkdown convertira votre document en diaporama en commençant une nouvelle diapositive à chaque en-tête ou règle horizontale (par exemple, ***).

Visite rmakdown.rstudio.com pour en savoir plus sur les options YAML qui contrôlent le processus de rendu.

résumer

Les documents R Markdown fournissent des rapports rapides et reproductibles à partir de R. Vous écrivez votre document en balisage et intégrez des fragments de code R exécutables avec Knitr syntaxe.

Vous pouvez mettre à jour votre document à tout moment en re-tricotant les fragments de code.

Vous pouvez ensuite convertir votre document en plusieurs formats courants.

Les documents R Markdown mettent en œuvre l’idée de Donald’s Knuth de programmation alphabète et simplifient le travail manuel lors de la rédaction et de la maintenance des rapports. De plus, ils apprennent vite. Vous connaissez déjà très bien Markdown, Knitr et YAML pour commencer à rédiger vos propres rapports R Markdown.

Dans le prochain article, Introduction aux documents interactifs, vous apprendrez à ajouter des composants Shiny interactifs à un rapport R. Markdown. Cela crée un flux de travail rapide pour l'écriture d'applications Shiny légères.

Pour en savoir plus sur R Markdown et les documents interactifs, visitez le site rmarkdown.rstudio.com.

Si vous avez des questions sur cet article ou si vous souhaitez discuter des idées présentées ici, veuillez poster sur Communauté RStudio. Nos développeurs surveillent ces forums et répondent aux questions périodiquement. Voir Aidez-moi pour plus d'aide avec tout ce qui est brillant.

#ecrire un livre technique
#écrire un livre méthode
#écrire un livre d’horreur