blocchi di codice R, opzioni, codice nel testo; un cenno a Python e OJS
Lo YAML
sintassi, livelli, opzioni principali, più formati
Il PDF
LaTeX e Typst
I report parametrici
un documento, tanti report
I progetti
un blog con i siti Quarto, una tesi con i libri Quarto e Typst
Materiale: questa presentazione, la scheda lab_14-attivita-quarto e la cartella lab_14-esempi (su Teams)
Come lavoriamo oggi
Ogni blocco segue lo stesso ciclo, ispirato al modello PRIMM (Predict, Run, Investigate, Modify, Make; Sentance, Waite e Kallia, 2019):
Osserva un esempio
Anticipa che cosa produrrà il sorgente, prima del rendering
Esegui il rendering e verifica se avevi ragione
Modifica l’esempio, o costruisci il tuo documento, con la scheda
Confronta soluzioni, errori e sorprese con il resto della classe
Oggi l’obiettivo è uscire dall’aula con un report, un blog e lo scheletro della tesi, tutti costruiti con lo stesso strumento.
Che cos’è Quarto
Un sistema di editoria scientifica e tecnica
Quarto è un sistema open source di editoria scientifica e tecnica, costruito su Pandoc.
— M. Çetinkaya-Rundel e C. Wickham, Quarto: The Definitive Guide
Editoria: non solo codice e risultati, ma documenti curati, pronti da pubblicare
Scientifica: equazioni, riferimenti incrociati, citazioni e bibliografia
Tecnica: il codice viene eseguito e i risultati entrano nel documento
Un sorgente, tanti prodotti:
report in html, Word e pdf
presentazioni html (come questa!) e PowerPoint
siti web e blog
libri e tesi
dashboard
articoli scientifici
Le radici: la literate programming
Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.
— D. E. Knuth (1984), Literate programming, The Computer Journal, 27(2), 97-111
L’idea di Knuth
un programma è anche un testo da leggere: spiegazione e codice si alternano nello stesso documento
dallo stesso sorgente si ricavano il codice da eseguire e la documentazione da leggere
Dalla programmazione all’analisi dei dati
2002: Sweave, testo LaTeX e codice R
2012: knitr e R Markdown
2022: Quarto, per R, Python, Julia e Observable JS
oggi: il report è l’analisi, e l’analisi si legge come un testo
Perché un sistema di editoria?
Il modo “tradizionale” di scrivere un report di analisi dei dati:
Copia e incolla
analisi in R
grafici salvati come immagini
numeri copiati a mano in Word
e se i dati cambiano?
Con Quarto
testo e codice nello stesso file
grafici, tabelle e numeri calcolati durante il rendering
se i dati cambiano, si rifà il rendering
il report è riproducibile
Riproducibile significa che chiunque, partendo dal sorgente e dai dati, ottiene lo stesso documento: è lo stesso principio dei vostri script, esteso all’intero report.
Come funziona: il rendering
flowchart LR
A["documento.qmd<br/>testo + codice"] --> B["knitr (R)<br/>Jupyter (Python)"]
B --> C["documento.md<br/>testo + risultati"]
C --> D["Pandoc"]
D --> E["html"]
D --> F["docx"]
D --> G["revealjs<br/>(slide html)"]
D --> P["pptx<br/>(PowerPoint)"]
D --> H["Typst / LaTeX"]
H --> I["pdf"]
Il motore di calcolo (knitr per R) esegue il codice e scrive un file markdown con testo e risultati; Pandoc lo converte nel formato finale; per il pdf serve un ulteriore passaggio, con Typst o LaTeX.
Gli strumenti
Dove si scrive
RStudio e Positron (e VS Code)
editor Source: il testo così com’è
editor Visual: anteprima della formattazione, menu per tabelle, immagini, equazioni
Come si ottiene il documento
pulsante Render (CTRL/CMD + SHIFT + K)
dal Terminale:
quarto render documento.qmdquarto preview documento.qmd
dalla console di R:
quarto::quarto_render("documento.qmd")
Il rendering avviene in una sessione di R nuova: il documento non vede gli oggetti del vostro ambiente di lavoro. Tutto ciò che serve (package, dati) va caricato nel documento.
Anatomia di un documento
Tre ingredienti
---title: "Ricchezza e salute delle nazioni"author: "Nome Cognome"format: html---## IntroduzioneQuesto report usa la tabella **gapminder**.```{r}library(gapminder)summary(gapminder$lifeExp)```
l’intestazione YAML, tra due righe ---: le opzioni del documento
il testo in markdown
i blocchi di codice (chunk), tra due righe ```
Dal sorgente al documento
Il report di esempio in html (cartella 01-report-statico)
Lo stesso sorgente in pdf, con Typst
Il testo: markdown
Markdown essenziale
Scrivo
Ottengo
## Titolo di sezione
un titolo di secondo livello (# primo livello, ### terzo)
Una riga vuota separa i paragrafi e deve precedere elenchi, titoli e blocchi di codice: dimenticarla è l’errore più frequente.
Le equazioni
Le equazioni si scrivono con la sintassi di LaTeX: tra $...$ nel testo, tra $$...$$ su una riga a sé.
Il modello di regressione è$$y_i = \beta_0 + \beta_1 x_i + \varepsilon_i$$con $\varepsilon_i \sim N(0, \sigma^2)$.
Il modello di regressione è
\[
y_i = \beta_0 + \beta_1 x_i + \varepsilon_i
\]
con \(\varepsilon_i \sim N(0, \sigma^2)\).
Blocchi speciali: i div
Tre “due punti” aprono e chiudono un blocco con uno stile particolare:
::: {.callout-tip}## Un consiglioSalvate spesso!::::::: {.columns}::: {.column width="50%"}colonna di sinistra:::::: {.column width="50%"}colonna di destra:::::::
.content-visible when-format="html" per mostrare un contenuto in un solo formato
Riferimenti incrociati e bibliografia
Come mostra la @fig-bolle, ...La @tbl-continenti riporta ...Nel @sec-dati descrivo ...Secondo @rosling2018factfulness ...... come noto [@wickham2023r4ds].
bibliography: riferimenti.bib
un’etichetta (label) con prefisso fig-, tbl- o sec- rende numerabile una figura, una tabella o una sezione
@etichetta produce “Figura 1”, “Tabella 2”, “Sezione 3”: la numerazione è automatica
le voci bibliografiche sono in un file .bib (esportabile da Zotero, Google Scholar, …)
@chiave cita, la bibliografia viene aggiunta in fondo
Con lang: it nello YAML, “Figure” diventa “Figura” e “Table of contents” diventa “Indice”.
Attività 1: il primo documento
Modifica - Scheda, attività 1
In un progetto lab14, crea il file primo-report.qmd (File → New File → Quarto Document) con:
titolo, autore, data e lang: it nello YAML
un’introduzione con un elenco, una parola in grassetto e un link
l’equazione della media campionaria e una nota a piè di pagina
un callout con un consiglio
Anticipa: dove compariranno il titolo e la nota? Fai il rendering in html e verifica.
Il codice
I blocchi di codice
```{r}#| label: fig-bolle#| fig-cap: "PIL pro capite e aspettativa di vita (2007)"#| echo: falseggplot(gap_2007, aes(x = gdpPercap, y = lifeExp, color = continent)) +geom_point() +scale_x_log10()```
il codice viene eseguito durante il rendering, e i risultati (testo, tabelle, grafici) entrano nel documento
le opzioni si scrivono all’inizio del blocco, su righe che iniziano con #|
i blocchi vengono eseguiti in ordine, nella stessa sessione: un oggetto creato in un blocco è disponibile nei successivi
in RStudio e Positron si inseriscono con CTRL/CMD + ALT + I
Le opzioni dei blocchi
Opzione
Effetto
echo: false
esegue il codice e mostra i risultati, ma non il codice
eval: false
mostra il codice senza eseguirlo
include: false
esegue il codice ma non mostra nulla (né codice né risultati)
output: false
esegue e mostra il codice, ma non i risultati
warning: false, message: false
nasconde avvertimenti e messaggi
error: true
in caso di errore il rendering prosegue e mostra l’errore
label: fig-..., fig-cap
etichetta e didascalia di una figura
fig-width, fig-height
dimensioni del grafico (in pollici)
label: tbl-..., tbl-cap
etichetta e didascalia di una tabella
Il codice nel testo
I numeri citati nel testo possono essere calcolati da R, con il codice inline:
La tabella contiene `r nrow(gapminder)` righe. Nel 2007l'aspettativa di vita media è di `r round(mean(gap_2007$lifeExp), 1)` anni.
diventa
La tabella contiene 1704 righe. Nel 2007 l’aspettativa di vita media è di 67 anni.
Mai scrivere a mano un numero che R può calcolare: se i dati cambiano, il testo si aggiorna da solo.
Il codice in uno script separato
Il flusso di lavoro dei tutorial del corso: il codice in uno script .R, il testo nel file .qmd.
```{python}import pandas as pddati = pd.read_csv("dati.csv")dati.describe()```
in un documento si usa un solo motore: knitr (anche per Python, con il package reticulate) o jupyter
Observable JS, eseguito nel browser
```{r}ojs_define(gap = gapminder)```
```{ojs}viewof anno = Inputs.range( [1952,2007], {step:5,label:"Anno"})```
R prepara i dati, OJS li rende interattivi nella pagina html
lo useremo per le dashboard
Esempio di prompt per un LLM per sfruttare OJS
Ho questo codice R, che usa i package tidyverse e gapminder, per creare un grafico a bolle:
gapminder::gapminder |>filter(year ==2007) |>ggplot() +aes(x = gdpPercap, y = lifeExp, color = continent) +geom_point(aes(size = pop)) +scale_x_log10()
Lo uso in un documento Quarto compilato in html. Vorrei usare Observable JS (OJS) per aggiungere dei controlli interattivi: un menu a tendina in cui l’utente seleziona il continente, e il grafico si aggiorna mostrando solo i paesi di quel continente. Il menu deve contenere anche l’opzione “Tutti”, che mostra tutti i dati ed è il valore di default.
Requisiti: passa i dati da R a OJS con ojs_define(); disegna il grafico con Observable Plot, mantenendo la scala logaritmica sull’asse x e la dimensione delle bolle proporzionale alla popolazione; non usare Shiny. Scrivi i blocchi di codice completi da inserire nel documento, con una breve spiegazione di ciascuno.
Esempio di prompt per un LLM: la richiesta successiva
Dopo aver provato il codice ricevuto, si prosegue nella stessa conversazione:
Ora dammi il codice con un menu a tendina per selezionare l’anno e cinque caselle di controllo per selezionare i continenti. Per default il grafico deve mostrare il primo anno disponibile nei dati, con tutte le caselle di controllo selezionate. Il resto del grafico (scale, colori, dimensione delle bolle) resta come prima.
Che cosa rende efficace un prompt
il contesto: package, dati, Quarto in html
il codice da cui partire
il comportamento atteso, descritto con precisione
i valori di default
i vincoli: che cosa usare e che cosa no
il formato della risposta
un passo alla volta: prima un controllo, poi gli altri
Il codice di un LLM va sempre eseguito e verificato: con quarto preview, provando le combinazioni dei controlli.
Attività 2: il codice nel documento
Modifica - Scheda, attività 2
Nel tuo primo-report.qmd:
aggiungi un blocco di setup (include: false) che carica tidyverse e gapminder e crea gap_2007
aggiungi una tabella dell’aspettativa di vita media per continente, con didascalia e riferimento incrociato
aggiungi un grafico con didascalia e riferimento incrociato, senza mostrare il codice
riporta nel testo, con il codice inline, il numero di paesi e l’aspettativa di vita media
Anticipa: che cosa succede se nel blocco di setup togli library(gapminder)?
Lo YAML
La sintassi
title:"Report: Gapminder 2007" # testo con ":" → tra virgoletteauthor:"Nome Cognome"date: todaylang: itformat: # le opzioni annidate sono rientratehtml: # di due spazi (mai la tabulazione)toc:true # valori logici: true / falsetoc-location: lefttheme:[cosmo, stile.scss] # un elenco tra parentesi quadre...typst: default # un formato con le opzioni di defaultbibliography: # ... o con i trattini- riferimenti.bib- altri.bib
Lo YAML è sensibile agli spazi: dopo i due punti serve uno spazio, e i rientri stabiliscono chi contiene chi. Un rientro sbagliato produce un errore, oppure un’opzione ignorata senza avvisi.
Dove si scrivono le opzioni
Livello
Dove
Vale per
progetto
file _quarto.yml
tutti i documenti del progetto
cartella
file _metadata.yml
i documenti della cartella
documento
intestazione YAML
il documento
formato
sotto format: html:
il documento, solo in quel formato
blocco
righe #|
il singolo blocco di codice
Le opzioni più specifiche vincono: un’opzione del blocco prevale su quella del documento, che prevale su quella della cartella e del progetto.
Le opzioni principali: il documento
Opzione
Significato
title, subtitle
titolo e sottotitolo
author
autore (o elenco di autori, con affiliazioni)
date, date-format
data (today = data del rendering) e suo formato, ad esempio "D MMMM YYYY"
lang
lingua del documento: it traduce “Figura”, “Indice”, …
abstract
riassunto
bibliography, csl
file della bibliografia e stile delle citazioni
number-sections
numera le sezioni
toc, toc-depth, toc-title
indice, sua profondità e suo titolo
execute
opzioni comuni a tutti i blocchi: echo, warning, message, freeze, …
il pulsante Render produce il primo formato; il menu accanto permette di scegliere gli altri
dal Terminale: quarto render report.qmd produce tutti i formati, quarto render report.qmd --to typst solo il pdf
alcune opzioni hanno senso solo in un formato: code-fold nel pdf viene ignorata
Attività 3: lo YAML
Modifica - Scheda, attività 3
Nel tuo primo-report.qmd:
aggiungi l’indice e la numerazione delle sezioni
cambia il tema (prova almeno tre temi)
nascondi codice, avvertimenti e messaggi di tutti i blocchi, con un’unica opzione
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?
Il pdf: LaTeX e Typst
Due strade per il pdf
LaTeX (format: pdf)
lo standard dell’editoria scientifica da decenni
richiede un’installazione a parte:
quarto install tinytex
compilazione lenta, messaggi di errore difficili
necessario se una rivista fornisce un modello LaTeX
Typst (format: typst)
un sistema tipografico moderno, disponibile pubblicamente dal 2023
incluso in Quarto: nessuna installazione
compilazione rapidissima
linguaggio di personalizzazione più semplice
la scelta che useremo nel corso
Le opzioni di Typst
format:typst:papersize: a4 # il default è us-lettermargin:x: 3cm # sinistro e destroy: 2.5cm # superiore e inferiorefontsize: 11ptcolumns:2 # testo su due colonnetoc:truenumber-sections:truesection-numbering: 1.1.a
Il pdf è un formato statico: niente codice “piegato”, grafici interattivi o animazioni. I grafici ggplot2 vengono inseriti come immagini.
Attività 4: il pdf con Typst
Modifica - Scheda, attività 4
Nel formato typst del tuo primo-report.qmd:
imposta il formato A4 e margini di 2.5 cm
prova columns: 2: che cosa succede al grafico?
cambia la dimensione del carattere
Anticipa: il callout dell’attività 1 comparirà anche nel pdf?
I report parametrici
Un documento, tanti report
Un report parametrico ha dei parametri nello YAML, usati dal codice come params$nome:
---title: "Il continente: `r params$continente`"params: continente: "Europe" anno: 2007---```{r}dati <- gapminder |>filter(continent == params$continente, year == params$anno)```Nel `r params$anno` i paesi sono`r nrow(dati)`.
i valori nello YAML sono quelli di default
al rendering si possono cambiare, senza toccare il documento
un solo sorgente produce un report per ogni continente, regione, anno, cliente, …
Con freeze: true il codice di un articolo viene rieseguito solo quando l’articolo cambia: i vecchi articoli restano come sono, anche se nel frattempo cambiano i dati o i package.
Il blog: un articolo
---title:"Quanto si vive nei diversi continenti?"author:"Nome Cognome"date:"2026-11-04"categories:[R, ggplot2, gapminder]image:"image.jpg"description:"Un articolo con codice R"---
Dopo lo YAML: testo e codice, come in qualunque documento Quarto.
Pubblicare il blog
GitHub Pages
quarto publish gh-pages
il progetto deve essere un repository GitHub
il sito sarà su nome-utente.github.io/mio-blog
Netlify
quarto publish netlify
oppure: quarto render e poi trascinare la cartella _site su Netlify Drop
Un blog con le vostre analisi è un ottimo portfolio: mostra che cosa sapete fare con i dati meglio di qualunque curriculum.
Attività 6: il tuo blog
Modifica - Scheda, attività 6
crea un progetto Quarto Blog di nome mio-blog
traduci in italiano la pagina iniziale e la pagina “About”, con lang: it in _quarto.yml
elimina gli articoli di esempio e scrivi due articoli: una presentazione e un’analisi di gapminder (riusa il tuo primo-report.qmd)
assegna categorie diverse ai due articoli e osserva la pagina iniziale
Anticipa: in che ordine compariranno gli articoli?
Una tesi con i libri Quarto
project:type: booklang: itbook:title:"Ricchezza e salute delle nazioni"subtitle:"Tesi di laurea magistrale"author:"Nome Cognome"date:"2026-11-04"chapters:- index.qmd- introduzione.qmd- dati.qmd- risultati.qmd- conclusioni.qmdbibliography: riferimenti.bibformat:html:theme: cosmotypst:papersize: a4toc:truenumber-sections:true
ogni capitolo è un file .qmd, l’ordine è stabilito in chapters
il primo file (index.qmd) è obbligatorio: una premessa, i ringraziamenti, …
i riferimenti tra capitoli funzionano: @sec-dati, @fig-continenti
la bibliografia viene raccolta in fondo al volume
lo stesso progetto produce un sito web e un pdf
La tesi in pdf con Typst
La copertina
Un capitolo
La versione html
Il codice R della tesi viene rieseguito a ogni rendering: grafici, tabelle e numeri sono sempre coerenti con i dati. Per un frontespizio istituzionale si può personalizzare il modello Typst.
Attività 7: lo scheletro della tesi
Modifica - Scheda, attività 7 (da completare a casa)
crea un progetto Quarto Book di nome mia-tesi
imposta titolo, autore, lang: it e i formati html e typst (A4)
crea i capitoli: premessa, introduzione, dati, risultati, conclusioni
nel capitolo dei risultati inserisci un grafico con un riferimento incrociato dal capitolo delle conclusioni
aggiungi un file riferimenti.bib con due voci e citale nell’introduzione
Anticipa: in quale capitolo comparirà la bibliografia nel pdf? E nella versione html?
Chiusura
Che cosa portiamo a casa
Quarto: un sorgente, tanti prodotti
YAML + markdown + blocchi di codice
le opzioni dei blocchi (#|) e del documento
riferimenti incrociati e bibliografia
numeri e grafici calcolati, mai copiati
il pdf con Typst
i report parametrici e quarto_render()
i progetti: _quarto.yml, _metadata.yml
un blog con i siti Quarto
una tesi con i libri Quarto
Prossimamente: le dashboard con Quarto, R e Observable JS
S. Sentance, J. Waite, M. Kallia (2019), Teaching computer programming with PRIMM: a sociocultural perspective, Computer Science Education, 29(2-3), 136-176: https://doi.org/10.1080/08993408.2019.1608781