Quarto in pratica

Attività in aula

Come funziona

Oggi impariamo Quarto costruendo, un pezzo alla volta, tre prodotti: un report, un blog e lo scheletro della tesi. Per ogni attività:

Osserva: il docente presenta un’idea con un esempio
Anticipa: prima del rendering, scrivi su un foglio (o come commento nel documento) che cosa ti aspetti di vedere
Esegui: fai il rendering e verifica se avevi ragione
Modifica: adatta l’esempio o costruisci il tuo documento
Confronta: discutiamo insieme le soluzioni, gli errori e le sorprese

Gli esempi mostrati in aula sono nella cartella file-esempio-quarto (su Teams): quando sei in difficoltà, apri il file corrispondente e confrontalo con il tuo.

Prima di iniziare

Crea un progetto RStudio di nome lezione-quarto (in Positron: crea una cartella lezione-quarto e aprila con File → Open Folder).
Verifica di avere installati i package tidyverse, gapminder, knitr, rmarkdown e quarto. Se manca qualcosa, installalo dalla console:

install.packages(c("tidyverse", "gapminder", "knitr", "rmarkdown", "quarto"))

Quarto è già incluso in RStudio e in Positron: non serve installarlo a parte.

Commenti in un documento Quarto

Nel testo di un documento Quarto il simbolo # non introduce un commento, ma un titolo. Per un commento che non compare nel documento finale si usa la sintassi .

Attività 1 - Il primo documento

Crea un nuovo documento Quarto (File → New File → Quarto Document), scegli il formato html e salvalo come primo-report.qmd nella cartella del progetto. Cancella il contenuto di esempio e scrivi un breve report su “Ricchezza e salute delle nazioni” con:

nello YAML: titolo, autore, data (today) e lang: it
una sezione “Introduzione” con un elenco puntato, una parola in grassetto e un link al sito di Gapminder
l’equazione della media campionaria, su una riga a sé
una nota a piè di pagina
un callout di tipo tip con un consiglio

Anticipa: dove compariranno il titolo e la nota? Fai il rendering e verifica.

Suggerimento

La media campionaria si scrive $$\bar{x} = \frac{1}{n} \sum_{i=1}^{n} x_i$$. Una nota si inserisce con ^[testo della nota]. Se l’editor visuale ti confonde, passa all’editor Source (in alto a sinistra): vedrai il testo esattamente come viene salvato.

Attività 2 - Il codice nel documento

Nel tuo primo-report.qmd:

aggiungi all’inizio un blocco di codice di setup che carica tidyverse e gapminder e crea la tabella gap_2007 con i dati del 2007; il blocco non deve comparire nel documento finale
aggiungi una sezione “I dati” con una tabella dell’aspettativa di vita media per continente nel 2007, con una didascalia; cita la tabella nel testo con un riferimento incrociato
aggiungi una sezione “Ricchezza e salute” con il diagramma di dispersione del PIL pro capite (in scala logaritmica) e dell’aspettativa di vita nel 2007, con una didascalia e senza mostrare il codice; cita la figura nel testo
riporta nel testo, con il codice inline, il numero di paesi e l’aspettativa di vita media nel 2007

Anticipa: che cosa succede se nel blocco di setup togli library(gapminder)? E se togli l’etichetta della figura?

Suggerimento

Un blocco di codice si inserisce con CTRL/CMD + ALT + I; le opzioni si scrivono all’inizio, su righe che iniziano con #|
#| include: false esegue il codice senza mostrare nulla; #| echo: false mostra i risultati ma non il codice
una tabella numerata ha #| label: tbl-nome e #| tbl-cap: "...", e il risultato di dplyr va passato a knitr::kable(); una figura numerata ha #| label: fig-nome e #| fig-cap: "..."
nel testo, @tbl-nome e @fig-nome producono “Tabella 1” e “Figura 1”
il codice inline si scrive tra un apice inverso seguito da r e un apice inverso: `r nrow(gap_2007)`

Attività 3 - Lo YAML

Nel tuo primo-report.qmd:

aggiungi l’indice e la numerazione delle sezioni
cambia il tema del documento html; prova almeno tre temi tra quelli elencati nella documentazione
nascondi codice, avvertimenti e messaggi di tutti i blocchi di codice con un’unica opzione nello YAML
aggiungi i formati typst e docx e produci i tre documenti

Anticipa: che cosa succede se rientri toc: true di un solo spazio invece che di due? E se scrivi toc:true, senza spazio?

Suggerimento

Le opzioni comuni a tutti i blocchi si scrivono sotto execute:. Le opzioni di un formato vanno sotto il nome del formato, rientrate di due spazi:

format:
  html:
    toc: true
  typst: default
  docx: default

Per produrre tutti i formati scrivi nel Terminale (non nella console di R): quarto render primo-report.qmd.

Attività 4 - Il pdf con Typst

Nelle opzioni del formato typst del tuo primo-report.qmd:

imposta il formato A4 e i margini di 2.5 cm
prova columns: 2: che cosa succede al grafico e alla tabella?
cambia la dimensione del carattere con fontsize

Anticipa: il callout dell’attività 1 comparirà anche nel pdf? E il codice “piegato” (code-fold), se lo avevi attivato nel formato html?

Attività 5 - Un report parametrico

Salva una copia del tuo primo-report.qmd con il nome report-anno.qmd e trasformalo in un report parametrico:

aggiungi nello YAML il parametro anno, con valore di default 2007
nel codice, sostituisci ogni 2007 con params$anno
fai comparire l’anno nel titolo e nelle didascalie
produci, dalla console di R, i report per il 1952 e per il 2007, con nomi di file diversi
produci con un ciclo un report per ciascuno degli anni 1952, 1977 e 2007

Anticipa: che cosa succede se passi un anno che non è nei dati, ad esempio 1950?

Suggerimento

library(quarto)
quarto_render("report-anno.qmd",
              execute_params = list(anno = 1952),
              output_file = "report-1952.html")

Nel titolo: title: "Ricchezza e salute nel `r params$anno`". In una didascalia: #| fig-cap: !expr paste("Ricchezza e salute nel", params$anno). Per il ciclo, guarda lo script genera-report.R nella cartella 02-report-parametrico degli esempi.

Attività 6 - Il tuo blog

crea un nuovo progetto Quarto Blog di nome mio-blog (File → New Project → New Directory → Quarto Blog)
nel file _quarto.yml aggiungi lang: it e cambia il titolo del blog
traduci in italiano la pagina iniziale (index.qmd) e la pagina about.qmd, con una breve presentazione
elimina gli articoli di esempio nella cartella posts e scrivi due articoli, ciascuno nella propria cartella: una presentazione del blog e un’analisi di gapminder (riusa il codice del tuo primo-report.qmd)
assegna ai due articoli date e categorie diverse, e un’immagine all’articolo di analisi
guarda il risultato con Render Website (o quarto preview nel Terminale)

Anticipa: in che ordine compariranno gli articoli nella pagina iniziale? Che cosa succede cliccando su una categoria?

Suggerimento

Il nome della cartella di un articolo diventa parte del suo indirizzo: usa nomi brevi, senza spazi, ad esempio 2026-11-04-gapminder. Lo YAML di un articolo contiene title, author, date, categories, image e description. Un esempio completo è nella cartella 03-blog.

Attività 7 - Lo scheletro della tesi (da completare a casa)

crea un nuovo progetto Quarto Book di nome mia-tesi
in _quarto.yml imposta titolo, sottotitolo (“Tesi di laurea magistrale”), autore, lang: it e i formati html e typst, con il formato A4
crea i capitoli: premessa (index.qmd), introduzione, dati, risultati, conclusioni, e indicali in chapters
nel capitolo dei risultati inserisci un grafico con etichetta e didascalia, e citalo dal capitolo delle conclusioni
crea un file riferimenti.bib con due voci e citale nell’introduzione

Anticipa: dove comparirà la bibliografia nel pdf? E nella versione html?

Suggerimento

Un capitolo con # Risultati {#sec-risultati} si cita con @sec-risultati. Le voci bibliografiche in formato BibTeX si ottengono da Google Scholar (icona delle virgolette → BibTeX) o da Zotero; nel testo si citano con @chiave o [@chiave], dove la chiave è la prima parola dopo la graffa, ad esempio wickham2023r4ds. Un esempio completo è nella cartella 04-tesi.

Per chi vuole fare di più

Python: se hai Python installato, aggiungi al tuo report un blocco {python} (in un nuovo documento con engine: jupyter)
Observable JS: apri l’esempio 05-ojs/ojs-esempio.qmd e visualizzalo con quarto preview nel Terminale; aggiungi un filtro per continente al tuo report
Pubblicazione: pubblica il tuo blog su GitHub Pages (quarto publish gh-pages) o su Netlify (quarto publish netlify)