11  Quarto

In questo capitolo imparerai a
  • utilizzare Quarto per creare report riproducibili e dinamici.
Prerequisiti
Preparazione del Notebook 
here::here("code", "_common.R") |> source()

# Load packages
if (!requireNamespace("pacman")) install.packages("pacman")
pacman::p_load(tidyr)

11.1 Introduzione

La crisi della riproducibilità scientifica rappresenta una delle sfide più importanti della ricerca contemporanea. Con questo termine ci si riferisce alla difficoltà, riscontrata in diverse discipline, di replicare i risultati degli studi scientifici. Sebbene le definizioni di riproducibilità varino tra i diversi ambiti, un’interpretazione ampiamente condivisa la identifica come la capacità di ottenere gli stessi risultati utilizzando i medesimi dati di input e seguendo gli stessi passaggi computazionali nei metodi e nelle analisi.

La pratica scientifica è profondamente radicata nella formazione accademica: ciò che viene insegnato nelle aule universitarie si riflette direttamente nel lavoro svolto nei laboratori, sul campo e nell’analisi dei dati. Riconoscendo questo stretto legame tra didattica e ricerca, molti studiosi sostengono l’importanza di integrare i metodi di riproducibilità nei corsi universitari di data science, sia a livello undergraduate che graduate (Dogucu, 2024). L’educazione alla data science che incorpora la riproducibilità nell’analisi dei dati viene infatti considerata la “controffensiva statistica” alla crisi della riproducibilità.

In questo contesto si inserisce Quarto, uno strumento innovativo che affronta direttamente le sfide della crisi della riproducibilità. Quarto si colloca nella tradizione del literate programming, un approccio pioneristico introdotto da Donald Knuth negli anni ’80. Questa metodologia nasce dalla visione di unificare codice e testo descrittivo in un unico documento, rendendo i programmi non solo eseguibili ma anche comprensibili agli esseri umani. L’obiettivo è superare la tradizionale separazione tra codice e documentazione, permettendo di spiegare non solo il funzionamento tecnico di un programma, ma anche le ragioni delle scelte implementative.

Questa filosofia risulta particolarmente pertinente nell’ambito della data science e dell’analisi statistica, dove riproducibilità e trasparenza sono requisiti imprescindibili. Quarto eccelle in questo contesto, offrendo la possibilità di integrare in codice, risultati e narrazione. La sua versatilità si manifesta nella capacità di produrre diversi tipi di output - dai report agli articoli scientifici, dalle presentazioni ai documenti tecnici - in vari formati come HTML, PDF e Word, combinando efficacemente testo interpretativo, risultati numerici e visualizzazioni grafiche.

Un punto di forza distintivo di Quarto è la sua flessibilità nel supportare molteplici linguaggi di programmazione, tra cui R, Python e Julia. Lo strumento può essere utilizzato secondo tre modalità principali: per presentare conclusioni condividendo i risultati senza esporre il codice sottostante; per documentare il processo analitico includendo sia il codice che i risultati, garantendo così piena trasparenza e riproducibilità; e per annotare l’analisi, integrando interpretazioni e motivazioni delle decisioni prese durante il processo analitico.

Nonostante Quarto sia tecnicamente uno strumento da riga di comando (CLI), l’integrazione con RStudio ne semplifica notevolmente l’utilizzo, rendendo l’installazione e l’operatività accessibili anche agli utenti meno esperti nell’uso del terminale. Questa caratteristica, unita alle sue potenti funzionalità, rende Quarto una naturale evoluzione del literate programming, offrendo un ambiente di lavoro che bilancia efficacemente praticità d’uso e rigore scientifico. In questo modo, Quarto si configura come una risposta concreta alle sfide della riproducibilità nella ricerca contemporanea, fornendo gli strumenti necessari per una scienza più trasparente e verificabile. L’obiettivo di questo capitolo è quello di fornire un’introduzione pratica a Quarto.

11.1.1 Creare un documento Quarto

Un file Quarto ha estensione .qmd e segue questa struttura:

Questo file include:

  1. Un’intestazione YAML (metadati del documento).
  2. Blocchi di codice delimitati da ```.
  3. Testo scritto in Markdown con formattazioni semplici come titoli (# Titolo), corsivi (*testo*), ecc.

11.1.2 Editor visivo e sorgente

  • Editor visivo: simile a Google Docs, offre un’interfaccia WYSIWYM (What You See Is What You Mean). Consente di inserire facilmente immagini, tabelle, citazioni e altro.
  • Editor sorgente: consente un controllo diretto sul Markdown, utile per debug e personalizzazioni avanzate.

11.1.3 Blocchi di codice

I blocchi di codice (chiamati “chunks”) eseguono codice e visualizzano i risultati. Ogni chunk è delimitato da ``` e può includere opzioni specifiche:

#| label: esempio
#| echo: false
1 + 1

Le opzioni più comuni includono:

  • echo: false (nasconde il codice nel report),
  • eval: false (non esegue il codice),
  • message: false e warning: false (nasconde messaggi o avvisi).

11.1.4 Figure

Le figure possono essere generate tramite codice (es. ggplot()) o inserite come file esterni. Le opzioni più comuni per il controllo delle dimensioni sono:

  • fig-width e fig-height (dimensioni della figura in pollici),
  • out-width (percentuale di larghezza del documento),
  • fig-asp (rapporto d’aspetto, es. 0.618 per il rapporto aureo).

Esempio:

#| fig-width: 6
ggplot(data, aes(x, y)) + geom_point()

11.1.5 Equazioni

Le equazioni possono essere scritte in \(\LaTeX\), così come spiegato nell’Appendice C.

11.1.6 Tabelle

Le tabelle possono essere stampate direttamente o personalizzate con funzioni come knitr::kable() o pacchetti come gt:

knitr::kable(head(mtcars))
mpg cyl disp hp drat wt qsec vs am gear carb
Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4
Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4
Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1
Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1
Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2
Valiant 18.1 6 225 105 2.76 3.460 20.22 1 0 3 1

11.1.7 Caching

Per velocizzare i documenti con calcoli complessi, Quarto supporta la memorizzazione dei risultati:

  • cache: true salva i risultati di un chunk, evitando di ricalcolarli se il codice non cambia.
  • dependson specifica dipendenze tra chunk.

11.1.8 Gestione delle Citazioni e delle Bibliografie in Quarto

Quarto offre un supporto avanzato per la generazione automatica di citazioni e bibliografie, consentendo l’applicazione di formati personalizzati come lo stile APA. Per includere riferimenti bibliografici, è necessario creare un file .bib (ad esempio, references.bib) contenente le citazioni nel formato BibTeX. Queste citazioni possono essere ottenute direttamente da Google Scholar o altri database accademici.

Ecco un esempio di una citazione in formato BibTeX:

@article{ceccarini2024age,
  title={Age-dependent changes in the anger superiority effect: Evidence from a visual search task},
  author={Ceccarini, Francesco and Colpizzi, Ilaria and Caudek, Corrado},
  journal={Psychonomic Bulletin \& Review},
  pages={1--10},
  year={2024},
  publisher={Springer}
}

Questa citazione deve essere inserita in un file .bib, ad esempio, references.bib. Tale file dovrà poi essere specificato nell’intestazione del documento Quarto.

11.1.8.1 Configurazione dell’Intestazione YAML

Nel file .qmd, è necessario aggiungere le seguenti righe all’intestazione YAML per collegare il file references.bib e configurare lo stile della bibliografia:

bibliography: references.bib
biblio-style: apalike
csl: apa.csl
  • bibliography: Specifica il percorso del file .bib. In questo esempio, si assume che il file si trovi nella stessa cartella del documento Quarto.
  • biblio-style: Imposta lo stile delle citazioni. Ad esempio, apalike è uno stile simile allo stile APA.
  • csl: Consente di utilizzare uno stile di citazione personalizzato, come apa.csl. Puoi scaricare facilmente questi stili dal Zotero Style Repository.

11.1.8.2 Esempio Completo

Di seguito è riportato un esempio completo di un documento Quarto che include una citazione e genera automaticamente la bibliografia:

---
title: "Articolo di Esempio"
author: "Autore di Esempio"
date: "2025-03-09"
bibliography: references.bib
biblio-style: apalike
csl: apa.csl
---

## Introduzione

In questo articolo, discutiamo i cambiamenti dipendenti dall'età nell'anger-superiority effect [@ceccarini2024age].

## Risultati

I risultati mostrano che...

## Riferimenti

In questo esempio, l’identificatore @ceccarini2024age viene utilizzato per fare riferimento alla citazione contenuta nel file references.bib. Al momento della compilazione, Quarto genererà automaticamente la lista dei riferimenti bibliografici in base al formato specificato.

11.1.8.3 Citazioni Inline

All’interno di un documento .qmd, le citazioni vengono aggiunte utilizzando il simbolo @ seguito dall’identificativo della citazione specificato nel file .bib. Ad esempio:

... come evidenziato da @ceccarini2024age, si osserva che...

Quarto genera automaticamente la bibliografia, includendo solo i riferimenti effettivamente citati nel documento. La bibliografia viene aggiunta alla fine del file renderizzato (ad esempio, in formato HTML o PDF).

Ad esempio, nel caso di un documento .qmd, il testo sopra sarà visualizzato così:

… come evidenziato da Ceccarini et al. (2024), si osserva che…

La citazione completa sarà inclusa automaticamente nella bibliografia, posizionata alla fine della pagina web o del documento finale. Si noti che Quarto gestisce automaticamente la formattazione e la posizione della bibliografia, garantendo coerenza e precisione.

Esempio 11.1 Per fare un esempio pratico, possiamo inserire la citazione @ceccarini2024age direttamente nel file .qmd di questa pagina web. Quando il documento viene compilato, Quarto renderà la citazione in modo appropriato, come mostrato qui: Ceccarini et al. (2024).

Si noti che, in fondo a questa pagina web, è presente un riferimento bibliografico corrispondente. Questo riferimento è stato aggiunto automaticamente da Quarto in risposta all’uso della citazione @ceccarini2024age nel testo del documento. Questo processo automatizzato semplifica la gestione delle citazioni e garantisce che tutti i riferimenti siano correttamente inclusi e formattati.

11.2 Riflessioni Conclusive

Quarto è uno strumento potente per la creazione di documenti riproducibili e ben strutturati, integrando codice, risultati e testo descrittivo in un unico file. Questa introduzione dovrebbe essere sufficiente per iniziare a lavorare con Quarto, ma c’è ancora molto da imparare. Il modo migliore per rimanere aggiornati è consultare il sito ufficiale di Quarto: https://quarto.org.

Un argomento importante che non abbiamo trattato qui riguarda i dettagli di come comunicare in modo accurato le proprie idee agli altri. Per migliorare le proprie capacità di scrittura, Wickham et al. (2023) consigliano due libri: Style: Lessons in Clarity and Grace di Joseph M. Williams & Joseph Bizup, e The Sense of Structure: Writing from the Reader’s Perspective di George Gopen. Una serie di brevi articoli sulla scrittura sono offerti da George Gopen e sono disponibili su https://www.georgegopen.com/litigation-articles.html.

11.3 Esercizi

In questo esercizio esplorerai l’importanza della riproducibilità nella scienza dei dati e le funzionalità principali di Quarto.

1. Concetti di base sulla riproducibilità

  1. Cos’è la crisi della riproducibilità e perché è rilevante nella scienza dei dati?
  2. In che modo Quarto può aiutare ad affrontare la crisi della riproducibilità?
  3. Spiega il concetto di literate programming e come si collega a Quarto.

2. Struttura di un file Quarto

  1. Qual è l’estensione di un file Quarto e quali sono le sue tre sezioni principali?
  2. Qual è la differenza tra editor visivo ed editor sorgente in Quarto?
  3. Qual è la funzione dell’intestazione YAML in un file .qmd?

3. Blocchi di codice e opzioni

  1. Come si scrive un blocco di codice in Quarto?
  2. Quali opzioni puoi utilizzare nei blocchi di codice per controllare l’esecuzione e la visualizzazione del codice e dei risultati?
  3. Scrivi un blocco di codice Quarto che calcola la media di un vettore di numeri e stampa il risultato senza mostrare il codice.

4. Figure e Tabelle

  1. Quali opzioni di formattazione delle figure offre Quarto?
  2. Come puoi creare una tabella formattata in Quarto usando knitr::kable()?

5. Citazioni e Bibliografia

  1. Come si aggiunge una citazione bibliografica in Quarto?
  2. Quali file devono essere inclusi per gestire una bibliografia in Quarto?
  3. Scrivi un esempio di citazione in formato BibTeX e mostra come collegarla a un documento .qmd.

6. Considerazioni Finali

  1. Quali sono i vantaggi di usare Quarto rispetto a strumenti più tradizionali come Word per la creazione di report scientifici?

1. Concetti di base sulla riproducibilità

  1. La crisi della riproducibilità è il fenomeno per cui molti studi scientifici non possono essere replicati con gli stessi metodi e dati. Questo mina la fiducia nella scienza e può portare a risultati non affidabili.
  2. Quarto aiuta la riproducibilità integrando codice, testo e risultati in un unico documento, rendendo più semplice verificare e riprodurre le analisi.
  3. Literate programming è un approccio introdotto da Donald Knuth che combina codice e spiegazioni testuali nello stesso file, migliorando la comprensione e documentazione delle analisi. Quarto segue questa filosofia.

2. Struttura di un file Quarto

  1. L’estensione di un file Quarto è .qmd. Le tre sezioni principali sono:

    • L’intestazione YAML (metadati),
    • Il codice (chunks),
    • Il testo scritto in Markdown.

  2. L’editor visivo è un’interfaccia intuitiva simile a Google Docs, mentre l’editor sorgente permette di scrivere direttamente in Markdown e codice.

  3. L’intestazione YAML definisce le proprietà del documento come titolo, autore, formato di output e opzioni di rendering.

3. Blocchi di codice e opzioni

  1. Un blocco di codice in Quarto si scrive con tripli backtick (```) e un linguaggio specificato:

    #| echo: true
print("Esempio di codice in Quarto")

  2. Alcune opzioni utili nei blocchi di codice sono:

    • echo: false per nascondere il codice,
    • eval: false per non eseguire il codice,
    • warning: false e message: false per nascondere messaggi e avvisi.

  3. Esempio di blocco di codice che calcola una media senza mostrare il codice:

    #| echo: false
mean(c(1, 2, 3, 4, 5))

11.4 4. Figure e Tabelle

  1. Le opzioni principali per le figure includono:

    • fig-width e fig-height per le dimensioni,
    • out-width per la larghezza relativa,
    • fig-asp per il rapporto d’aspetto.

  2. Per creare una tabella formattata con knitr::kable():

    knitr::kable(head(mtcars))

5. Citazioni e Bibliografia

  1. Le citazioni in Quarto si aggiungono usando il simbolo @ seguito dal riferimento BibTeX (es. @ceccarini2024age).

  2. Per gestire la bibliografia in Quarto servono:

    • Un file .bib con le citazioni,
    • Un’intestazione YAML che collega il file .bib e specifica lo stile (csl).

  3. Esempio di citazione BibTeX e collegamento in YAML:

    @article{ceccarini2024age,
  title={Age-dependent changes in the anger superiority effect},
  author={Ceccarini, Francesco et al.},
  journal={Psychonomic Bulletin & Review},
  year={2024}
}

    YAML:

    bibliography: references.bib
biblio-style: apalike

6. Considerazioni Finali

  1. I vantaggi di Quarto rispetto a Word includono:

    • maggiore riproducibilità e trasparenza,
    • possibilità di integrare codice ed esecuzione in un unico documento,
    • facilità di gestione delle citazioni automatiche,
    • supporto per diversi formati di output (HTML, PDF, Word).

Informazioni sull’Ambiente di Sviluppo

sessionInfo()
#> R version 4.4.2 (2024-10-31)
#> Platform: aarch64-apple-darwin20
#> Running under: macOS Sequoia 15.3.1
#> 
#> Matrix products: default
#> BLAS:   /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/lib/libRblas.0.dylib 
#> LAPACK: /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.0
#> 
#> locale:
#> [1] C/UTF-8/C/C/C/C
#> 
#> time zone: Europe/Rome
#> tzcode source: internal
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#>  [1] thematic_0.1.6   MetBrewer_0.2.0  ggokabeito_0.1.0 see_0.10.0      
#>  [5] gridExtra_2.3    patchwork_1.3.0  bayesplot_1.11.1 psych_2.4.12    
#>  [9] scales_1.3.0     markdown_1.13    knitr_1.49       lubridate_1.9.4 
#> [13] forcats_1.0.0    stringr_1.5.1    dplyr_1.1.4      purrr_1.0.4     
#> [17] readr_2.1.5      tidyr_1.3.1      tibble_3.2.1     ggplot2_3.5.1   
#> [21] tidyverse_2.0.0  rio_1.2.3        here_1.0.1      
#> 
#> loaded via a namespace (and not attached):
#>  [1] generics_0.1.3    stringi_1.8.4     lattice_0.22-6    hms_1.1.3        
#>  [5] digest_0.6.37     magrittr_2.0.3    evaluate_1.0.3    grid_4.4.2       
#>  [9] timechange_0.3.0  fastmap_1.2.0     rprojroot_2.0.4   jsonlite_1.9.1   
#> [13] mnormt_2.1.1      cli_3.6.4         rlang_1.1.5       munsell_0.5.1    
#> [17] withr_3.0.2       tools_4.4.2       parallel_4.4.2    tzdb_0.4.0       
#> [21] colorspace_2.1-1  pacman_0.5.1      vctrs_0.6.5       R6_2.6.1         
#> [25] lifecycle_1.0.4   htmlwidgets_1.6.4 pkgconfig_2.0.3   pillar_1.10.1    
#> [29] gtable_0.3.6      glue_1.8.0        xfun_0.51         tidyselect_1.2.1 
#> [33] rstudioapi_0.17.1 farver_2.1.2      htmltools_0.5.8.1 nlme_3.1-167     
#> [37] rmarkdown_2.29    compiler_4.4.2

Bibliografia

Ceccarini, F., Colpizzi, I., & Caudek, C. (2024). Age-dependent changes in the anger superiority effect: Evidence from a visual search task. Psychonomic Bulletin & Review, 1–10.
Dogucu, M. (2024). Reproducibility in the Classroom. Annual Review of Statistics and Its Application, 12.
Wickham, H., Çetinkaya-Rundel, M., & Grolemund, G. (2023). R for data science. " O’Reilly Media, Inc.".