Integrato nativamente in RStudio, e basato sulla sintassi Markdown, RMarkdown serve a creare report riproducibili a partire dagli script di R, producendo documenti in vari formati che combinano testo formattato, codice e risultati.

Il modo più semplice per capire come funziona è creare ed esportare il primo documento.

In RStudio, il menu per creare un nuovo file è (ovviamente) File > New File > RMarkdown, che apre una finestra di dialogo che chiederà di scegliere, fra le altre cose, il formato del documento (ad esempio, HTML, PDF, Word, ecc.).

Il documento appena creato (scegliendo il formato HTML) si presenterà come segue:

---  
title: "Documento RMarkdown"  
author: "Nome Cognome"  
date: "Oggi"  
output: html_document  
--- 

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

## R Markdown

This is an R Markdown document. Markdown is a simple formatting syntax for 
authoring HTML, PDF, and MS Word documents. For more details on using R 
Markdown see <http://rmarkdown.rstudio.com>.

When you click the **Knit** button a document will be generated that 
includes both content as well as the output of any embedded R code chunks 
within the document. You can embed an R code chunk like this:

```{r cars}
summary(cars)
```

## Including Plots

You can also embed plots, for example:

```{r pressure, echo=FALSE}
plot(pressure)
```

Note that the `echo = FALSE` parameter was added to the code chunk 
to prevent printing of the R code that generated the plot.

Il testo di prova già inserito nel testo fornisce le istruzioni (in inglese) per iniziare a usare questi documenti, e mostra alcuni esempi di formattazione e di blocchi eseguibili.

Per la formattazione del testo, vedi Guida alla sintassi Markdown.

Il cuore del documento è ovviamente rappresentato dal codice, che va inserito in un blocco di codice, come quello che segue.

```{r}  
# questo è un commento in un blocco di codice   
print("Ciao!")
```  

In RStudio, questi blocchi di codice possono essere eseguiti direttamente nel documento, cliccando sulla freccia verde in alto a sinistra rispetto al blocco (run, simile a play). Questo consente di analizzare / visualizzare i dati e commentarli contemporaneamente.

Proviamo a scrivere qualcosa, ad esempio:

Questo è un testo normale, che uso per commentare 
il blocco di codice eseguibile R, che è quello che segue.
 
```{r}  
# questo è un commento in un blocco di codice   
print("Ciao!")
```  

Anche se sembra banale … Salvare il file appena creato, altrimenti il file di output non verrà generato.

Dopo il primo salvataggio, il file verrà salvato sempre, prima del rendering.

Il processo che trasforma un file .Rmd in un documento formattato (HTML, PDF, Word, ecc.) si chiama rendering.

Cliccando su “Knit” (indicato con l'icona del gomitolo, o di un block notes per i notebook) si genererà il documento di output¹⁾.

Nella figura che segue, il rendering è quello predefinito per i notebook, ovvero l’anteprima in HTML.

Il tipo e il formato del documento dipenderà naturalmente dalla scelta fatta al momento della creazione del file: il rendering da menu (pulsante) avverrà automaticamente per quel formato.

È possibile però cambiarlo o aggiungerne un altro (dal menu a tendina, o a mano), e quindi produrre da uno stesso file più tipi di documenti.

---  
title: "Documento RMarkdown"  
author: "Il tuo nome"  
date: "Oggi"  
output:
  word_document: default
  html_notebook: default
---  

I formati accettati sono svariati (anche se non tutti sono inclusi esplicitamente nel menu): oltre a “word_document”, “pdf_document”, “html_document”, possiamo indicare “odt_document”, “powerpoint_presentation”, e altri ancora (vedi I formati di RMarkdown).

Il rendering può essere eseguito anche da riga di comando, o script:

rmarkdown::render(file, output_format = "word_document")

La parte iniziale del file .Rmd, delimitata da ---, si chiama front matter (o frontmatter):

---  
title: "Documento RMarkdown"  
author: "Il tuo nome"  
date: "Oggi"  
output:
  word_document: default
  html_notebook: default
---   

Il front matter è un elemento di fondamentale importanza in tutti i file markdown, in quanto contiene i metadati, quali il titolo del documento, l’autore, la data e soprattutto, come abbiamo visto sopra, il tipo di output desiderato, ed eventualmente altre istruzioni necessarie alla corretta generazione del documento (ad esempio, quelle per i riferimenti bibliografici).

Alcune di queste informazioni, a seconda del formato di output scelto, verranno inserite direttamente nel documento: ad esempio, il titolo indicato nel front matter sarà il titolo principale del documento finale generato.

Vedi anche: Pandoc: guida introduttiva

I blocchi di codice eseguibili (code chunks) sono la componente fondamentale di un documento RMarkdown, in quanto permettono di inserire ed eseguire codice R (o anche altri linguaggi, ma R è quello predefinito).

Essi sono delimitati da:

• Tre backtick ``` seguiti dall'estensione del linguaggio fra parentesi graffe {r};
• e tre backtick alla fine: ```

```{r}
# commento
codice
```

Fortunatamente, per inserirli senza doverli scrivere, in RStudio esistono

• una scorciatoia, Ctrl-Alt-I; e
• un pulsante, evidenziato nell’immagine che segue.

Quando il documento RMarkdown viene compilato, il codice all’interno di questi blocchi viene eseguito e i risultati (come tabelle, grafici, output testuali) vengono inseriti nel documento finale, insieme al testo normale scritto al di fuori dei blocchi.

Vedi anche: Sintassi di Markdown: i blocchi di codice

I blocchi possono essere personalizzati con opzioni che controllano cosa viene mostrato nel documento finale.

Queste opzioni si scrivono nella testata del blocco²⁾, ad esempio:

```{r pressure, echo=FALSE}
# non mostra il codice, mostra solo l'output
plot(pressure)
```

RStudio semplifica la gestione dei blocchi con un menu a tendina che appare cliccando sulla rotellina⚙️in alto a destra di ogni chunk.

Le impostazioni per l'intero documento sono incluse nel file di esempio creato automaticamente:

```{r setup, include=FALSE}
# in tutto il documento, verranno mostrati codice e output
# i blocchi potranno comunque essere impostati ad hoc
knitr::opts_chunk$set(echo = TRUE)
```

library(LabRS)
data(MYSLID)
tab1 <- table(MYSLID$Lingua)
tab3 <- table(MYSLID$Lingua, MYSLID$Genere)

All'interno di un report di ricerca, le tabelle sono un elemento fondamentale. Markdown permette di costruire tabelle che hanno qualche limitazione (per la formattazione base, vai a Markdown: le tabelle).

Per ovviare a tali limitazioni, esistono pacchetti specializzati, che in ogni caso richiedono di conoscere la sintassi di base e il modo in cui rmarkdown tratta (passando da knitr e *Pandoc*) le tabelle, le didascalie, la numerazione delle tabelle e i riferimenti incrociati.

Questa che segue è una tabella normale, così come la vediamo nella console di R, e incollata in un file di testo.

        
           Donna Uomo
  Inglese   2999 2717
  Francese   262  235
  Altro      564  527

Utilizzando la funzione kable() del pacchetto knitr (comunque usato per il rendering dei documenti RMarkdown:

```{r}
kable(tab3, caption = "didascalia")
```

la tabella verrà prima trasformata in markdown (in background, a meno che non eseguiate il comando in uno script o in console):

 

|          | Donna | Uomo |
|----------|------:|-----:|
| Inglese  |  2999 | 2717 |
| Francese |   262 |  235 |
| Altro    |   564 |  527 |

: didascalia

e poi trasformata (con Pandoc, e sempre in background) in una tabella compatibile con il formato scelto.

Per la formattazione dei grafici nel file di Word, possono essere utili le seguenti opzioni dei blocchi di codice:

Ad esempio:

```{r fig.cap="Esempio di grafico a barre"}
barplot(
  tab1, 
  main = "Lingue"
```

Per visualizzare solo il grafico senza il codice:

```{r echo=FALSE, fig.cap="Esempio di grafico a barre"}
barplot(
  tab1, 
  main = "Lingue"
```

Questo file si può scaricare, ed usare per generare un file html (notebook) o un file Word.

primo_documento.Rmd

---
title: "Primo documento RMarkdown"
author: "Nome Cognome"
date: "`r Sys.Date()`"
output:
  word_document: default
  html_notebook: default
---
 
I blocchi possono avere un nome.
 
```{r pacchetti}
library(LabRS)
library(knitr)
```
 
```{r dati}
data(MYSLID)
tab1 <- table(MYSLID$Lingua)
tab3 <- table(MYSLID$Lingua, MYSLID$Genere)
```
 
Questa è una tabella con didascalia
 
```{r}
kable(tab3, caption = "didascalia")
```
 
Questo è un grafico con didascalia, ma nel documento non si vedrà il codice
 
```{r echo=FALSE, fig.cap="Esempio di grafico a barre"}
barplot(
  tab1, 
  main = "Lingue"
)
```