6.2 R-markdown

Un linguaggio di markup permette di aggiungere mediante marcatori (tag) informazioni sulla struttura e sulla formattazione da applicare ad un documento. Un’introduzione al linguaggio Markdown può essere trovata, per esempio, qui oppure qui.

In questo capitolo ci focalizzeremo però sugli aspetti più importanti di R-markdown che permette di costruire documenti in cui combinare testo formattato (quindi non solo commenti ma anche formule, titoli etc) e istruzioni codice (R e non solo) con i corrispettivi output. Informazioni dettagliate su R-markdown sono disponibili qui e qui.

Un file R-markdown è composto da tre tipi di oggetti:

1. header in formato YAML delimitato da ---,
2. testo in formato markdown,
3. blocchi (“chunks”) di codice R, delimitati da tre apici.

6.2.1 Header

L’intestazione di un documento .Rmd (R-markdown) corrisponde al cosiddetto YAML header (un acronimo che significa Yet Another Markup Language). Lo YAML header controlla le caratteristiche generali del documento, incluso il tipo di documento che viene prodotto (un documento HTML che può essere visualizzato su tutti i principali browser, un documento Microsoft Word o un PDF se abbiamo installato LaTeX sul nostro computer), la dimensione del carattere, lo stile, il titolo, l’autore, ecc. Nello YAML header (a differenza del codice R) è necessario rispettare la spaziatura prestabilita delle istruzioni che vengono elencate. Gli elementi principali sono title:, author:, output:.

L’argomento di output: è dove diciamo a R-markdown quale tipo di file vogliamo che venga prodotto. Il tipo più flessibile, che non richiede alcuna configurazione, è html_document.

6.2.2 Testo

Alla conclusione dello YAML header inizia il documento R-markdown. Da questo punto in poi possiamo utilizzare testo normale, codice R e sintassi Markdown per controllare cosa viene mostrato e come.

6.2.3 Formattazione

È possibile contrassegnare intestazioni, grassetto e corsivo come indicato di seguito.

# Intestazione 1
## Intestazione 2
### Intestazione 3
#### Intestazione 4
##### Intestazione 5
###### Intestazione 6

Questo è un testo normale.
Possiamo scrivere in **grassetto** il testo usando due asterischi.
Possiamo scrivere in *corsivo* usando un asterisco.

>Questa è un’**area rientrata**.

Questa riga invece non è più rientrata.

6.2.4 Elenchi

Per creare un elenco puntato si utilizza il segno più, il trattino o l’asterisco. Tutte le tre soluzioni portano allo stesso risultato.

- Punto 1 della lista
- Punto 2 della lista
- Punto 3 della lista

Un elenco numerato, invece, si crea con un numero seguito da un punto.

1. Punto 1 della lista
2. Punto 2 della lista
3. Punto 3 della lista

6.2.5 Hyperlink

Per inserire un hyperlink ci sono due metodi:

• specificare solo il percorso <http://rmarkdown.rstudio.com>, http://rmarkdown.rstudio.com
  
• creare un link con [link](http://rmarkdown.rstudio.com)
  

6.2.6 Immagini

Per inserire un’immagine la sintassi è molto simile: ![Esempio di immagine inserita in un documento R-markdown.](images/hex-rmarkdown.png){width=20%}:

Esempio di immagine inserita in un documento R-markdown.

6.2.7 Codice inline

Per contrassegnare un’area di testo come codice, markdown utilizza il cosiddetto backtick, noto anche come gravis o accento grave, da non confondere con la virgoletta singola. La marcatura prevede un accento all’inizio e uno alla fine dell’area di testo corrispondente.

Questo è `codice`.

6.2.8 Equazioni

Equazioni possono essere inserite in un documento R-markdown usando la sintassi . Qualsiasi cosa all’interno del segno di dollaro $ viene trattata come un’equazione “inline”. Qualunque cosa all’interno di due segni di dollaro $$ viene trattata come un’equazione a sé stante.

Per esempio, questa è la formula della distribuzione Normale espressa in notazione LaTeX e riprodotta all’interno di un documento R-markdown:

f(x) = \frac{1}{\sigma\sqrt{2\pi}}
  \exp\left( -\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^{\!2}\,\right)

\[ f(x) = \frac{1}{\sigma\sqrt{2\pi}} \exp\left( -\frac{1}{2}\left(\frac{x-\mu}{\sigma}\right)^{\!2}\,\right) \]

6.2.9 Codice R

In un documento R-markdown istruzioni di codice vengono inserite in blocchi delimitati da tre apici. Ciò consente di valutare il codice all’interno del documento e di produrre un output che verrà stampato nel documento stesso. Possiamo dunque stampare tabelle e figure prodotti direttamente dal codice R. Ciò significa inoltre, che se qualcosa cambia nei dati o nelle analisi dei dati, le tabelle e le figure si aggiorneranno automaticamente.

Un chunk R viene valutato proprio come il normale codice R, quindi si applica tutto ciò che abbiamo imparato nei capitoli precedenti. Se il chunk R produce un output, questo output verrà visualizzato nel documento.