8 Creare report e notebook con R.

v1.0 9/9/2023

8.1 Cosa c’è da imparare in questo capitolo.

Comunicare i risultati delle proprie analisi statistiche è, ovviamente, una necessità per qualsiasi ricercatore. Come avrai notato, l’output (grafici, tabelle, analisi statistiche) prodotto da questo libro compare nel testo, insieme a parti di testo o a immagini statiche disponibili su file: il libro è, in effetti, scritto con bookdown, un pacchetto di R creato apposta per facilitare la scrittura di libri o di articoli lunghi, che si appoggia largamente su rmarkdown, un pacchetto per la creazione di report in un gran numero di formati:

  1. notebook e documenti in .html: si possono aprire con qualsiasi browser e possono includere elementi interattivi, creati per esempio con shiny163;

  2. documenti in PDF; per questo tipo di documenti è necessario installare sul proprio sistema una implementazione di LaTeX: la versione suggerita è tinyTeX;

  3. documenti in MS Word (ma anche in altri formati per wordprocessor, come .odt e .rtf);

  4. presentazioni in HTML (con ioslides e Slidy), in PDF (con Beamer) e in powerpoint;

  5. una varietà di altri documenti interattivi, come libri e dashboard;

rmarkdown è una versione di markdown, un linguaggio minimalista per creare testi contenenti codici di formattazione con dei semplici editor di testi (come per esempio gli script di R creati nel source pane di RStudio).
Sia markdown che rmarkdown sono diversi dagli editor di testi cui siamo abituati sotto forma di software di wordprocessing come MS Word, Pages, Google Documents, etc. che dai campi di testo formattato che incontriamo nei moduli interattivi di molti siti web, che, utilizzano menu e barre di accesso rapido, consentono di avere un approccio WYSIWYG (what you see is what you get): se evidenziate una porzione di testo con il mouse e applicate il formato grassetto usando un menu o un comando rapido il testo vi apparirà immediatamente in grassetto. Con le varie versioni di markdown, invece, dovrai applicare dei codici di formattazione (p.es. un testo in grassetto è preceduto e seguito da due asterischi, vedi dopo)164.
In questo breve capitolo proverò a fornire il minimo di informazioni per la creazione di semplici report come documenti in HTML e PDF (i due formati leggibili sostanzialmente su qualsiasi piattaforma e facilmente pubblicabili sul web), o in formato leggibile da MS Word (e altri wordprocessor capaci di importare file .docx).
In realtà, se hai fretta, il paragrafo 8.2 ti fornisce abbastanza informazioni per creare, con pochissimo sforzo il tuo primo report.

8.2 Il minimo indispensabile.

Per essere del tutto sincero con te, il modo più semplice di creare un report è usare la funzione File -> Compile report... di RStudio con uno script di R. Prova tu stess* con questo codice che devi copiare e incollare in un nuovo script (e salvare):

#' uno script minimalista con commenti in stile ROxygen
print("hello world!")

#' un riassunto
summary(cars)

#' un piccolo grafico

plot(pressure)

File -> Compile report... apre un piccolissimo menu che ti consente di salvare un report che include del testo (estratto dai commenti, vedi dopo), il codice e i risultati dell’analisi in un formato a scelta fra HTML, PDF e MS Word. I commenti scritti con #' sono commenti in stile ROxygen e vengono resi come testo nella compilazione del report. Se si crea un report in un formato editabile (MS Word) è poi facile aprirlo e arricchire i commenti e le discussioni. Tuttavia, il livello di controllo sulla formattazione e le opzioni sono decisamente limitati. Anche per * più pigr* meglio usare Rmarkdown.

RStudio fornisce una semplicissima procedura guidata per la creazione di documenti rmarkdown: è sufficiente usare il menu File -> New file -> Rmarkdown... per vedere aprire una finestra interattiva che guida alla creazione di un documento minimo, come mostrato in figura 8.1. ***

Creare un documento rmarkdown da menu.

Figura 8.1: Creare un documento rmarkdown da menu.

Il documento può poi essere facilmente modificato per aggiungere altre opzioni o elementi. A questo proposito le versioni più recenti di RStudio offrono 2 opzioni:

  • l’uso di codici di formattazione (vedi figura 8.2)

  • un editor visuale (vedi figura 8.3)

Source: usare codici di formattazione per documenti RMarkdown.

Figura 8.2: Source: usare codici di formattazione per documenti RMarkdown.

La prima opzione permette la massima flessibilità, con l’uso di codici di formattazione descritti p.es. nel menu Help -> Markdown Quick Reference e dalle Cheat Sheets di RMarkdown (disponibili anche queste nel menu Help -> Cheat Sheets). Per esempio, nella figura 8.2:

  • lo YAML header, che fornisce opzioni generali sul documento è delimitato da ---

  • i chunk di rodice in R sono delimitati tre virgolette singole con {r nomechunk} che indica il nome del chunk (deve essere unico) e le opzioni165

  • e intestazioni di 2° livello sono precedute da un doppio cancelletto

  • il testo in neretto è preceduto e seguito da un doppio asterisco

Inoltre i tasti di accesso rapido nella parte superiore del pane consentono di accedere a varie funzioni:

  • salvare il documento

  • eseguire correzione ortografica (purché la lingua sia impostata correttamente) o eseguire le funzioni cerca e cerca/sostituisci

  • produrre il report (knit) in vari formati (quello definito dall’header, in questo caso .html, o altri), eseguendo il codice dei chunk

  • cambiare le opzioni di visualizzazione

  • inserire chunk di diversi tipi di codice

  • passare da un chunk all’altro

  • far girare uno o più chunk

  • mostrare la struttura del documento166

D’altra parte, il visual editor facilita notevolmente la creazione di report con formattazioni complesse anche a chi proprio non vuole perdere tempo a imparare i codici di formattazione (figura 8.3)

Visual: documenti RMarkdown usando il visual editor.

Figura 8.3: Visual: documenti RMarkdown usando il visual editor.

Il significato dei menu e dei tasti di accesso rapido è molto intuitivo (in alcuni casi è necessario selezionare del testo per applicare uno stile). Usando il visual editor è possibile:

  • applicare rapidamente stili al testo (neretto, italico, codice)

  • applicare stili ai paragrafi (Normal, Heading 1, etc.)

  • creare elenchi puntati e numerati

  • inserire e formattare immagini esterne e link

  • applicare formati addizionali a testi e blocchi

  • inserire una varietà di elementi (figure, blocchi di codice, etc.)

  • inserire e formattare tabelle

Prova a creare un documento vuoto e usando File -> New File -> R Markdown ... ed esplora le opzioni dei diversi menu per familiarizzarti.
Quanto hai fatto prova a cliccare su Knit nella barra dei menu del source pane o ad aprire il menu Knit e a scegliere un tipo di documento di destinazione.

Bene, a questo punto dovresti essere in grado di creare dei semplici report. Prova a utilizzare codice dai capitoli precedenti per arricchirli di figure, tabelle e calcoli, e ad usare il visual editor per cambiare la formattazione.

La creazione di presentazioni non è difficile: basta ricordare che le diverse diapositive sono individuate da intestazioni di primo livello (cancelletto singolo).

8.3 Gli elementi di un report in R Markdown.

Un report (e più in generale un documento) di R Markdown è caratterizzato da diversi elementi principali:

  • il YAML header: contiene i metadati di base del documento (titolo, autore, tipo di documento, etc.)

  • intestazioni di diveso livello (precedute da uno o più #), che definiscono la struttura del documento

  • blocchi di testo, contenenti opzionalmente formattazioni di diverso tipo, inclusi elenchi puntati e numerati, figure, hyperlink167, equazioni e altro codice in formato LaTeX

  • blocchi di codice (tipicamente di r, ma non solo), delimitati da tre apostrofi singoli (figura 8.2) e da un’intestazione contenente ozioni: come minimo il tipo di blocco (r), il nome del blocco (che deve essere utile), seguiti eventualmente da una virgola che delimita le opzioni. Le opzioni sono numerosissime (vedi la cheat sheet e la chear sheet con il manuale di riferimento di R Markdown) e riguardano:

    • opzioni sull’esecuzione del codice e sul suo inserimento nel documento definitivo: p.es. eval = F significa che il codice del chunk non verrà eseguito mentre include = F significa che il codice verrà eseguito ma non verrà inserito nel docuemnto finale. In generale un primo chunk con il nome setup può contenere opzioni globali che si applicano a tutti i chunk successivi.

    • opzioni sulle figure: risoluzione (p.es. dpi = 96), dimensioni (fig.height, fig.width) e molte altre

    • opzioni sui risultati: includono la possibilità di mostrare errori, warning, messaggi e molto altro

    • etc.

Un altro elemento importante è la presenza di codice in line: si tratta di brevi frammenti di codice delimitati da virgolette singole del tipo: “r mean(mpg$hwy, na.rm = F)” (qui ho usato le virgolette doppie per non far eseguire il codice).

Questi frammenti di codice, di solito composti da un solo comando molto breve possono servire a inserire in modo riproducibile numeri all’interno del testo. Per esempio, ammettiamo che un dato documento riporti, fra le altre cose, dati metereologici di una determinata area per un determinato intervallo di tempo. Invece di dover inserire manualmente ogni volta che si aggiornano i dati la temperatura media, è sufficiente calcolarla in un frammento di codice in line.

Le possibilità di formattazione di R Markdown sono veramente incredibili ed esulano dagli sopi di questo testo: per approfondire puoi usare il materiale citato nella sezione 8.6.

8.4 Altri formati di documento con R Markdown.

Oltre che dei report contenenti testo e risultati di analisi R Markdown consente di produrre molti altri formati di documento. I principali sono:

  • le presentazioni: PDF con beamer, HTML con ioslides, slidy o reveal.js, PowerPoint

  • le dashboard: create con flexdashboard o altri strumenti, sono un modo flessibile per mostrare risultati di analisi statistiche e grafiche

  • documenti interattivi con htmlwidgets e Shiny che permettono agli utenit di interagire con l’analisi tramite menu e campi di testo

Inoltre, è possibile creare libri e documenti complessi con bookdown e creare persino siti web.

La creazione delle presentazioni non è molto difficile. Usando le cheat sheet è relativamente facile creare delle semplici presentazioni, tenendo conto che le intestazioni di primo livello e secondo livello creano le slide, che possono anche essere separate manualmente da ---.
Insomma, c’è un po’ da studiare, ma le possibilità di counicazione sono veramente notevoli (e vanno ben oltre lo scopo, limitato, di questo testo).

8.5 Quarto.

Le versioni più recenti di RStudio supportano anche Quarto, un sistema di pubblicazione scientifica forse più complesso, articolato e flessibile di rmarkdown. Una guida completa è qui.

8.6 Altre risorse.

8.6.1 Risorse in italiano.

Tranne qualche articolo di blog, che potete trovare facilmente con un ricerca con il vostro motore di ricerca preferito, francamente, non ho trovato niente di notevole.

8.6.2 Risorse in inglese.

Come sempre, c’è a scegliere

  • il punto di partenza migliore è sicuramente il menu Help di RStudio, con una quick reference su Markdown e un paio di utilissime cheatsheet, che è bene tenere sempre a portata di mano

  • il sito di Posit fornisce un’eccellente introduzione a rmarkdown: un po’ lunghetta, ma vale la pena

  • sul sito di bookdown, oltre a tante altre belle cose (si fa per dire) ci sono:

    • un libro di ricette e una guida completa a rmarkdown, entrambe ottime guide di riferimento, ma un tantino pesanti da leggere

    • un testo molto completo sulla pubblicazione di libri con bookdown: anche questo completo e autorevole, ma un tantino pesante

  1. la differenza fra i due tipi di documento è che i notebook sono più utili nella fase di scrittura e per persone più esperte nell’uso di R perché consentono di far girare indipendentemente i singoli “chunk” di codice producendo il loro output immediatamente sotto il chunk, mentre i documenti HTML sono destinati, come dire, agli utilizzatori finali, che possono anche non avere nessuna esperienza in R. Fra le altre cose, i notebook danno come risultato un file con estensione .nb.html, che contiene sia il documento definitivo che il file .Rmd, che può essere estratto e riutilizzato; tuttavia, i notebook potrebbero non funzionare correttamente se si lavora con alcuni sistemi di cloud, come Google Drive, che potrebbero creare difficoltà con la sincronizzazione della cache del notebook.↩︎

  2. in realtà, le versioni più recenti di RStudio mettono a disposizione un editor visuale↩︎

  3. è possibile inserire anche chunk di altri linguaggi, come Python, C++, Stan, etc.↩︎

  4. è consigliabile uno schermo grande↩︎

  5. un hyperlink ha il formato [testo](URL)↩︎