Quarto: un sistema di pubblicazione scientifica e tecnica open source

Author

Domenico Vistocco

Il rendering di un documento Quarto

Quando esegui il rendering di un documento Quarto, knitr esegue tutti i blocchi di codice e crea un nuovo documento markdown (.md), che include il testo statistico, il codice e il suo output. Il file markdown generato viene quindi elaborato da pandoc, che crea il formato finito. Il pulsante Render incapsula queste azioni e le esegue nell’ordine giusto:

Un report Quarto si compone di due sezioni:

  • la sezione YAML (Yet Another Markup Language), che contiene i metadati che regolano il funzionamento del documento di output,

  • il testo del report, che si compone di testo statico e di pezzi (chunk) di codice.

Il linguaggio usato per la composizione del testo è il Markdown. Le regole di base del linguaggio Markdown sono consultabili su questo link, mentre la documentazione ufficiale di Quarto contiene una guida dettagliata per l’utilizzo del sistema.

Per iniziare ad utilizzare Quarto ti consiglio di studiare i tre tutorial disponibili sulla pagina ufficiale:

  1. Hello Quarto

  2. Computations

  3. Authoring

Temi del documento Quarto

E’ possibile sfruttare una serie di temi predefiniti per formattare il report Quarto. Per dettagli si rimanda alla pagina HTML Theming della documentazione ufficiale.

Editor online per le equazioni

Le equazioni in un documento Quarto vanno inserite utilizzando la sintassi di LaTeX, che è il linguaggio standard per l’editoria scientifica. Per comporre le equazioni puoi aiutarti sfruttando uno dei tanti tool disponibili online che ti permettono di ottenere la sintassi LaTeX scegliendo i simboli da inserire in un editor visuale. Ecco un elenco non esaustivo di alcune pagine che puoi sfruttare per questo scopo:

Editor online per le tabelle

Per inserire una tabella statica (non generata cioè da R), puoi sfruttare sia l’editor visuale disponibile in RStudio che le seguenti pagine dove puoi comporre una tabella usando un editor visuale e richiedere in output il codice Markdown da copiare ed incollare in Quarto (attenzione: il codice Markdown va inserito quando l’editor è in formato Source):

Un esempio di report con codice R integrato

Puoi visualizzare su questo link un esempio di report Quarto con codice integrato.

Un esempio di report con codice R su file esterno

Nel flusso standard di lavoro, si procede prima alla scrittura del codice e solo alla fine alla redazione del report con i risultati. Sebbene sia possibile copiare il codice utile nei vari chunk di Quarto, è utile tenere separati i file di codice (script R) e i file dei report (file .qmd di Quarto). Questo anche per evitare duplicazione di codice che potrebbe essere causa di errori in fase di aggiornamento degli script.

E’ possibile mantenere separato il codice R e il testo statico sfruttando la funzione read_chunk() disponibile nel package knitr. In questo caso

Puoi scaricare da questo link un esempio di report Quarto con codice esterno.

Un esempio di report parametrico

Puoi visualizzare:

  • su questo link un esempio di report Quarto parametrico con codice R integrato,

  • su questo link lo stesso report parametrico con codice R esterno.

Puoi compilare un report parametrico sfruttando la funzione quarto_render() del package quarto (da installare) usando questa linea di codice nel caso in cui vuoi sfruttare i valori di default definiti nella sezione YAML:

quarto::quarto_render(input = "lab_14-report-quarto-parametrico_codice-integrato.R")

Puoi cambiare i valori di default impostando una lista per l’argomento execute_params della funzione quarto_render:

quarto::quarto_render(input = "lab_14-report-quarto-parametrico_codice-integrato.R", 
                      execute_params = list(continente = "Europe"))
quarto::quarto_render(input = "lab_14-report-quarto-parametrico_codice-integrato.R", 
                      execute_params = list(continente = "Europe"), 
                      output_file = "report_output.html")

Dettagli tecnici (avanzati)

Puoi naturalmente sfruttare le funzioni di R per generare automaticamente i report per differenti valori degli input e personalizzare i nome dei file di output:

lst_paesi <- c("Italy", "France", "Jamaica", "Kuwait", "Mexico")

# per dettagli su questo comando si rimanda alle lezioni delle prossime settimane
purrr::walk(lst_paesi, 
            function(x){
              quarto::quarto_render(
                input = "lab_14-report-quarto-parametrico_codice-integrato.R",
                execute_params = list(continente = x),
                output_file = paste0("report_", x, ".html"))
            })

Progetto RStudio con i vari tipi di report

💻️ Un esempio di report Quarto con codice integrato

💻️ Un esempio di codice Quarto con codice esterno

💻️ Un esempio di report Quarto parametrizzato con codice integrato

💻️ Un esempio di report Quarto parametrizzato con codice esterno

Nota

Puoi scaricare qui il progetto RStudio in formato compresso con tutto il necessario per compilare sul tuo PC i quattro report Quarto.