Last chance! 50% off DataCamp Premium
Sale ends in
In questo articolo esploreremo un pacchetto essenziale e utile per la data science che ogni utente R dovrebbe conoscere—R Markdown. Impareremo cos'è R Markdown, quali vantaggi offre, a cosa serve, come installarlo, quali possibilità mette a disposizione per lavorare con codice, testo narrativo e grafici, quale sintassi utilizza, i formati di output dei documenti R Markdown e come renderizzare tali documenti e condividerli con i nostri collaboratori.
Poiché R Markdown è particolarmente integrato con l'ambiente di sviluppo integrato (IDE) RStudio, useremo questo IDE per tutto l'articolo. Il tutorial su RStudio fornisce le indicazioni necessarie per installare RStudio e iniziare a usarlo.
Cominciamo!
Cos'è R Markdown?
R Markdown è un pacchetto R gratuito e open source che offre uno spazio di lavoro per creare progetti di data science. Il vantaggio principale di R Markdown è che ti permette di combinare codice, testo e visualizzazioni dei dati in un unico documento rifinito, condivisibile e completamente riproducibile, che può essere renderizzato in un'ampia varietà di formati di output, sia statici che interattivi.
Alcuni dei suoi formati di output più popolari sono HTML, PDF, Microsoft Word, presentazioni, applicazioni, siti web, dashboard, report, template, articoli, libri, ecc.
Inoltre, R Markdown consente un facile tracciamento del controllo di versione e supporta molti linguaggi di programmazione oltre a R, tra cui Python e SQL.
Se vuoi approfondire come creare report dinamici con R Markdown, il corso Reporting with R Markdown è il posto giusto da cui partire.
Installare R Markdown
Quando usiamo R Markdown al di fuori di RStudio, lo installiamo come qualunque altro pacchetto R dal repository CRAN (Comprehensive R Archive Network):
install.packages("rmarkdown")Dopo l'installazione, dobbiamo caricare il pacchetto nell'ambiente di lavoro R:
library(rmarkdown)Invece, lavorando con R Markdown all'interno di RStudio—come faremo in tutto questo tutorial—non è necessario installare e caricare esplicitamente il pacchetto rmarkdown. Cliccando su File—New File—R Markdown nella barra dei menu di RStudio, si aprirà un nuovo documento R Markdown. A questo punto, potremmo ricevere una notifica Install Required Packages, come segue:
Dopo aver confermato l'installazione dei pacchetti richiesti, nella nuova finestra pop-up che appare inseriamo il titolo del documento e il nome dell'autore (entrambi opzionali ma consigliati), lasciamo le altre impostazioni così come sono e premiamo OK:
Documento R Markdown predefinito
Nella sezione precedente abbiamo aperto un nuovo documento R Markdown in RStudio. Si presenta così:
Vediamo che include il titolo, il nome dell'autore, la data corrente e il formato di output predefinito che abbiamo fornito nella finestra pop-up al momento dell'apertura. Poi contiene alcuni esempi della sintassi di base usata da R Markdown, come aggiungere e formattare i blocchi di codice, inserire intestazioni, link, enfasi del testo e generare grafici.
Ora analizzeremo più da vicino diverse funzionalità di R Markdown e la relativa sintassi. Per il momento, salviamo questo file predefinito e poi renderizziamolo nel formato di output selezionato (nel nostro caso—HTML) per vedere che aspetto ha.
Per salvare il file, clicchiamo su File—Save As... nella barra dei menu di RStudio.
NOTA: il nome del documento R Markdown che abbiamo fornito prima non coincide con il nome del file. Dobbiamo salvare il file nella directory del progetto e poi ricordarci di salvarlo regolarmente di tanto in tanto (File—Save) mentre ci lavoriamo.
Per renderizzare il file salvato nel formato di output selezionato (HTML), dobbiamo premere Knit nella toolbar del file:
Ecco come appare il nostro documento R Markdown predefinito nel formato HTML:
Formattazione del testo in R Markdown
Spesso il testo costituisce la parte principale di un progetto di data science. Perciò è importante sapere come formattarlo in R Markdown per renderlo facile da leggere, efficace e coinvolgente.
Se vuoi imparare a usare R per l'analisi dei dati e la data science e far crescere sia le tue competenze di programmazione in R che quelle di data science, valuta i seguenti percorsi professionali per principianti e completi:
Intestazioni
Possiamo aggiungere vari livelli di intestazioni al nostro documento R Markdown usando il simbolo cancelletto (#). Ecco la sintassi:
# Intestazione 1 (titolo principale)
## Intestazione 2 (sezione)
### Intestazione 3 (sottosezione)
ecc.
Una volta renderizzate, le intestazioni di cui sopra appariranno così:
Enfasi del testo
R Markdown permette di aggiungere diversi tipi di enfasi al testo, come corsivo, grassetto, barrato, apice o pedice, come segue:
- *corsivo* oppure _corsivo_
- **grassetto** oppure __grassetto__
- ~~barrato~~
- testo^apice^
- testo~pedice~
Di seguito è mostrato come queste enfasi appaiono nella versione renderizzata:
Elenchi
Per creare un elenco non ordinato, usiamo una delle seguenti tre sintassi:
* Voce 1* Voce 2* Voce 3
oppure:
- Voce 1- Voce 2- Voce 3
oppure:
+ Voce 1+ Voce 2+ Voce 3
In tutti i casi, il risultato renderizzato sarà lo stesso:
Per creare un elenco ordinato, usiamo la seguente sintassi:
1. Voce 12. Voce 23. Voce 3
Il risultato renderizzato apparirà simile, con un'indentazione aggiunta prima di ogni numero.
Nota che se eliminiamo una voce da un elenco ordinato, ne aggiungiamo una nuova o semplicemente commettiamo un errore in uno dei numeri (ad esempio, se scriviamo 20. invece di 2. nell'esempio sopra), i numeri verranno corretti automaticamente e mostrati come previsto:
Citazioni a blocchi
Per le citazioni a blocchi, usiamo il simbolo > prima del primo carattere del testo da citare:
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam hendrerit nisi sed sollicitudin pellentesque. Nunc posuere purus rhoncus pulvinar aliquam. Ut aliquet tristique nisl vitae volutpat. Nulla aliquet porttitor venenatis. Donec a dui et dui fringilla consectetur id nec massa. Aliquam erat volutpat. Sed ut dui ut lacus dictum fermentum vel tincidunt neque.
Questo verrà renderizzato così:
Aggiungiamo una riga vuota dopo un blocco citato per uscirne.n elenco non ordinato di 3 elementi
Link
Se vogliamo includere un link come percorso diretto, dobbiamo racchiudere l'URL tra i simboli < e >. Ad esempio, la seguente costruzione:
verrà renderizzata come:
Invece, per ancorare un link a una parola o a un breve testo, dobbiamo usare la seguente sintassi (usando ancora il sito di Google come esempio):
[Google](https://www.google.com/)
Questo verrà renderizzato come:
Immagini
Per inserire un'immagine nella nostra narrazione, usiamo uno dei seguenti approcci:
- Se vogliamo aggiungere un'immagine da Internet:
- Se il file immagine è salvato nella cartella del progetto dove si trova il nostro documento R Markdown:
- Se il file immagine è salvato sul nostro computer ma al di fuori della cartella del progetto:
Il testo alternativo fornisce una breve informazione su ciò che è raffigurato e viene utilizzato quando un utente non riesce a vedere l'immagine sulla pagina, per qualsiasi motivo.
Vediamo il primo approccio in azione per una immagine su Pixabay, con l'URL https://cdn.pixabay.com/photo/2018/12/02/10/07/web-3850917_1280.jpg:
Quando renderizziamo il documento, l'immagine viene mostrata:
Interruzioni
Esistono vari tipi di interruzioni in R Markdown:
- Interruzione di riga—per iniziare una nuova riga. Si ottiene terminando la riga precedente con un backslash (\).
- Interruzione di paragrafo—per iniziare un nuovo paragrafo. Si ottiene terminando il paragrafo precedente con due spazi.
- Interruzione di slide—per iniziare una nuova slide nei formati di output basati su slide (presentazioni) o una nuova sezione in tutti gli altri formati. Si ottiene inserendo una linea orizzontale (***) nel documento.
- Interruzione di pagina—per iniziare una nuova pagina, nei formati di output in cui è applicabile, ad esempio in Microsoft Word. Si ottiene inserendo il comando \newpage nel documento.
Mettiamo in pratica i primi tre tipi di interruzioni. Di seguito un brano di testo Lorem ipsum con alcuni simboli di formattazione per le interruzioni in R Markdown:
Lorem ipsum dolor sit amet, consectetur adipiscing elit.\Nam hendrerit nisi sed sollicitudin pellentesque.
Nunc posuere purus rhoncus pulvinar aliquam.
***
Ut aliquet tristique nisl vitae volutpat.
Ecco come verrà renderizzato in un documento HTML:
Lorem ipsum dolor sit amet, consectetur adipiscing elit.Nam hendrerit nisi sed sollicitudin pellentesque.
Nunc posuere purus rhoncus pulvinar aliquam.
Ut aliquet tristique nisl vitae volutpat.
Formattazione ed esecuzione del codice in R Markdown
Il codice è un altro componente essenziale di qualsiasi progetto di data science. In R Markdown possiamo eseguire il codice (e non solo in linguaggio R), mostrare sia il codice che il suo output, mostrare solo il codice e nasconderne l'output, mostrare solo l'output e nascondere il codice sorgente, ecc.
Il percorso professionale per principianti R Programmer e il percorso di competenze R Programming sono risorse utili per imparare, esercitarti e affinare le tue abilità di coding in R.
Blocchi di codice
Per formattare ed eseguire un blocco di codice R in R Markdown, lo racchiudiamo tra una coppia di triple backtick, con le prime triple backtick seguite da una r tra parentesi graffe. Ad esempio:
```{r}
print("Hello, World!")
```Se renderizziamo il documento senza eseguire il codice, il nostro blocco apparirà così:
Linguaggio del codice
Lavorando con R Markdown, non siamo limitati all'uso di R poiché questo pacchetto supporta anche molti altri linguaggi di programmazione. Per eseguire un pezzo di codice in un altro linguaggio, indichiamo il nome del linguaggio al posto di R tra le parentesi graffe. Inoltre, potremmo dover installare e caricare alcuni pacchetti aggiuntivi nell'ambiente di lavoro R.
Ad esempio, per poter usare Python in R Markdown, dobbiamo installare e caricare il pacchetto reticulate che consente una comunicazione bidirezionale (come creare e accedere a variabili) tra Python e R nello stesso documento R Markdown.
R riscriviamo il pezzo di codice della sezione precedente in Python (dopo aver installato e caricato il pacchetto reticulate):
```{python}
print("Hello, World!")
```
Esecuzione dei blocchi di codice
Per eseguire un blocco di codice o le righe selezionate al suo interno quando lavoriamo con R Markdown in RStudio, clicchiamo sul pulsante Run nella toolbar del documento e selezioniamo l'opzione necessaria dal menu a discesa:
Nell'immagine sopra vediamo che ogni opzione di esecuzione ha la sua scorciatoia da tastiera, che possiamo usare invece di aprire ogni volta il menu a discesa.
Denominazione dei blocchi di codice
Sebbene non sia obbligatorio, è una buona pratica dare un nome ai blocchi di codice. Può essere utile in molti casi: per fare riferimento ai blocchi nel documento, per il debugging del codice, per passare da un blocco all'altro, ecc. La denominazione dei blocchi diventa particolarmente importante se lavoriamo con un documento lungo che contiene molti blocchi.
Aggiungiamo il nome di un blocco tra parentesi graffe, subito dopo il nome del linguaggio, separandolo con uno spazio. Il nome di un blocco non deve contenere spazi.
Nell'esempio seguente, abbiamo aggiunto il nome hello_world al blocco:
```{r hello_world}
print("Hello, World!")
```Opzioni dei blocchi di codice
Le opzioni dei blocchi di codice ci permettono di controllare valutazione del codice, output, decorazione, cache, animazioni (se applicabili) e grafici (se applicabili)—tutto questo per ciascun blocco individuale. Possiamo aggiungere più opzioni allo stesso blocco. A livello di sintassi, inseriamo le opzioni tra parentesi graffe subito dopo il nome del blocco (se presente; altrimenti dopo il nome del linguaggio), separate da esso e tra loro da una virgola.
In R Markdown sono disponibili molte opzioni per i blocchi. Ognuna ha un valore predefinito, ma quando decidiamo di usarle probabilmente vorremo un valore diverso da quello di default. Vediamo le opzioni più popolari e i loro valori che potrebbero interessarci:
echo=FALSE—il codice in sé non verrà mostrato nel documento finale, ma solo i suoi output.eval=FALSE—il codice nel blocco non verrà eseguito.include=FALSE—il blocco verrà eseguito ma non incluso nel documento finale.results—il valore predefinito è "markup"; altri valori sono:- "hide"—l'output del codice sarà nascosto nel documento finale
- "hold"—l'output del codice verrà mostrato con un ritardo, solo dopo l'esecuzione dell'intero blocco
- "asis"—l'output del codice verrà passato senza riformattazione.
message=FALSE—i messaggi prodotti dal codice non verranno mostrati.error=FALSE—gli errori prodotti dal codice non verranno mostrati.warning=FALSE—gli avvisi prodotti dal codice non verranno mostrati.highlight=FALSE—il codice non verrà evidenziato nel documento finale.prompt=TRUE—il simbolo > verrà aggiunto all'inizio di ogni riga di codice mostrata nel documento finale.
Di seguito alcuni esempi di blocchi di codice che sono stati prima eseguiti in R Markdown in RStudio e poi renderizzati nel documento finale:
Codice in R Markdown:
Output nel documento finale:
Codice inline
Con il codice inline possiamo inserire direttamente brevi porzioni di codice nel testo del nostro documento R Markdown—verranno eseguite e i loro output saranno mostrati incorporati nel testo. La sintassi del codice inline è r <code>.
Di seguito un semplice esempio di testo contenente codice inline:
There are `r 1+6` colors of the rainbow.
e come viene renderizzato nel documento finale:
There are 7 colors of the rainbow.
In pratica, il codice inline si usa per aggregare informazioni sui dati e aiuta a evitare errori che possono capitare facilmente se inseriamo i numeri manualmente o se i dati cambiano.
Creare grafici in R Markdown
Creare grafici in R Markdown implica eseguire codice che genera figure. Quindi, tutto ciò che abbiamo discusso finora sulla formattazione ed esecuzione del codice in R Markdown, tranne il codice inline, si applica anche alla creazione di grafici. La differenza principale è che l'output di tale codice sarà grafico piuttosto che solo testo e numeri.
Il percorso di competenze Data Visualization with R ti aiuterà a sviluppare le competenze necessarie per analizzare e visualizzare i dati in R e, quindi, raccontare storie migliori guidate dai dati.
Per personalizzare i grafici in R Markdown, come nel R "base", usiamo gli strumenti dei pacchetti di visualizzazione dei dati di R, nonché la funzione plot() del R base.
Tuttavia, per controllare il comportamento dei grafici in un documento R Markdown, possiamo usare opzioni dei blocchi relative solo alla grafica. La maggior parte di esse è piuttosto specifica e, quindi, al di fuori dell'ambito di questo tutorial introduttivo. Diamo dunque un'occhiata ad alcune opzioni di base che possono essere utili quando si creano grafici in R Markdown:
fig.show—il valore predefinito è "asis"; altri valori sono:- "hide"—i grafici verranno generati ma non inclusi nel documento finale
- "hold"—i grafici verranno mostrati con un ritardo, solo dopo l'esecuzione dell'intero blocco
- "animate"—tutti i grafici del blocco verranno combinati in un'animazione.
fig.width—larghezza del grafico in pollici, predefinita 7.fig.height—altezza del grafico in pollici, predefinita 7.fig.align—allineamento dei grafici nel documento finale; può essere "left", "center" o "right".fig.cap—didascalia della figura rappresentata da una stringa di caratteri.fig.path—percorso della directory in cui salvare i file dei grafici creati dal blocco.fig.ext—estensione dei file dei grafici creati dal blocco.
Di seguito alcuni esempi di utilizzo di blocchi specifici per la grafica in R Markdown, inclusi il codice sorgente e l'output renderizzato:
Codice in R Markdown:
Output nel documento finale:
Formati di output
Finora abbiamo considerato solo il documento HTML (html_document) come formato di output per il documento finale. Tuttavia, R Markdown offre molti altri formati di output, tra cui Microsoft Word, Microsoft PowerPoint, PDF, quaderni R interattivi, dashboard, ecc.
Ad esempio, i formati di output disponibili in R Markdown per creare documenti includono html_document, pdf_document, word_document, github_document, html_notebook, html_vignette, ecc. Invece, per creare presentazioni, possiamo usare i seguenti formati di output: powerpoint_presentation, ioslides_presentation, slidy_presentation e beamer_presentation.
Per impostare un formato di output per il nostro documento R Markdown, assegniamo il valore corrispondente all'impostazione output nell'intestazione del documento (nota anche come intestazione YAML, dove YAML sta per yet another markup language). Ad esempio, per il nostro documento R Markdown di lavoro, il formato di output è impostato su html_document, che è anche il formato predefinito in R Markdown:
Per cambiarlo, sostituiamo html_document con il formato necessario (pdf_document, word_document, powerpoint_presentation, ecc.). Ora, quando premiamo Knit nella toolbar del file, renderizzeremo il documento nel formato di output selezionato.
Pubblicare documenti R Markdown
Per pubblicare un documento R Markdown, clicchiamo su File—Publish nella barra dei menu di RStudio e selezioniamo dove vogliamo pubblicarlo:
Poi seguiamo le ulteriori istruzioni che dipenderanno dalla scelta precedente e premiamo Publish. Ora il nostro documento è pronto per essere condiviso con i collaboratori.
Conclusione
Per concludere, in questo articolo abbiamo visto come iniziare con R Markdown. Per prima cosa abbiamo definito cos'è R Markdown e a cosa serve. Poi abbiamo discusso come installare R Markdown, come formattare il testo e le sue varie componenti, come formattare ed eseguire il codice, come generare grafici, quali formati di output offre R Markdown, come renderizzare un documento di lavoro in uno di questi formati e come pubblicare il documento finale per condividerlo con i colleghi.
Per fare un po' di pratica con R Markdown, dai un'occhiata al nostro corso Reporting with R Markdown, che ti aiuterà a far emergere insight dai dati e a presentare i risultati come PDF, file HTML o app Shiny.
Argomenti
