HW 07 - Report con Quarto

Data di consegna: giovedì 12 novembre 2026

Introduzione

In questo compito non scriverai uno script, ma dei documenti Quarto: report che uniscono testo, codice R, tabelle e grafici, e che si ricostruiscono da soli quando i dati cambiano. Userai ancora i dati del sistema bibliotecario cittadino dell’esercitazione 1. Il compito è diviso in tre parti:

nella Parte 1 costruirai un report statico, prodotto in formato html e in formato pdf con Typst
nella Parte 2 aggiungerai al report html un controllo interattivo con OJS, con l’aiuto di un LLM
nella Parte 3 costruirai un report parametrico, con un report per ciascuna biblioteca generato automaticamente

In questo compito utilizzerai i comandi utili per:

scrivere un documento Quarto: intestazione YAML, testo in markdown, blocchi di codice
inserire tabelle e figure numerate, con didascalie e riferimenti incrociati
inserire nel testo numeri calcolati da R con il codice inline
citare una bibliografia
produrre lo stesso documento in più formati
aggiungere un controllo interattivo con OJS
creare un report parametrico e automatizzarne il rendering con quarto_render e le funzioni map e walk del package purrr

Obiettivi di apprendimento

Lo svolgimento di questo compito ti permetterà di:

capire il principio della literate programming: testo e codice nello stesso documento, risultati sempre aggiornati
scegliere le opzioni dei blocchi di codice in base a che cosa deve vedere il lettore del report
leggere e correggere lo YAML, rispettando rientri e sintassi
formulare a un LLM una richiesta precisa e verificarne la risposta

Istruzioni per l’uso

Crea un progetto RStudio di nome hw07 (in Positron: crea una cartella hw07 e aprila con File → Open Folder) e lavora all’interno del progetto per tutto il compito.
All’interno della cartella del progetto crea una sottocartella dati e salva al suo interno i file dei dati dell’esercitazione 1 (utenti.csv, prestiti.xlsx e catalogo.txt), che trovi anche su Teams, allegati al compito.
Nella cartella del progetto creerai tre file:
- report_biblioteche.qmd, il report statico delle Parti 1 e 2
- report_biblioteca.qmd, il report parametrico della Parte 3
- genera_report.R, lo script che produce i report parametrici
Nei documenti Quarto, le risposte alle domande che chiedono un’interpretazione vanno scritte nel testo del report, nella sezione indicata dal punto. Nello script genera_report.R, usa invece i commenti e le etichette di sezione, come nei compiti precedenti.
I documenti devono poter essere prodotti senza errori con il pulsante Render (o con quarto render nel Terminale), e lo script deve funzionare quando si eseguono tutti i comandi con il pulsante Source.
Rispetta le regole di stile viste in aula, anche nei blocchi di codice dei documenti Quarto: nomi degli oggetti in snake case, <- per l’assegnazione, spazi attorno agli operatori e dopo le virgole, una istruzione per riga, un a capo dopo ogni pipe e dopo ogni + dei grafici ggplot2.
I documenti vengono valutati sia in base alla correttezza del codice che in base alla qualità del report: ordine, chiarezza del testo, cura di tabelle e grafici.

I package necessari

Oltre ai package usati nei compiti precedenti, per questo compito servono i package knitr, quarto e purrr: knitr e purrr sono già installati con il tidyverse. Se necessario, installa quarto dalla console:

install.packages("quarto")

Quarto è già incluso in RStudio e in Positron: non serve installarlo a parte. Il pdf viene prodotto con Typst, anch’esso incluso in Quarto.

Le tabelle con la funzione kable

Per inserire una tabella in un report basta passare un data frame (ad esempio il risultato di count, summarise o tabyl) alla funzione kable del package knitr, che lo trasforma in una tabella formattata, adatta sia all’html che al pdf:

library(knitr)
utenti |>
  count(categoria) |>
  kable(col.names = c("Categoria", "Utenti"))

Gli argomenti più utili sono:

col.names: i nomi delle colonne da mostrare, in un vettore di stringhe con un nome per ciascuna colonna
digits: il numero di cifre decimali, uno solo per tutte le colonne o uno per ciascuna colonna
align: l’allineamento delle colonne, ad esempio align = "lrr" (sinistra, destra, destra)
format.args = list(big.mark = ".", decimal.mark = ","): i separatori delle migliaia e dei decimali all’italiana

La didascalia e l’etichetta per il riferimento incrociato non si indicano in kable, ma nelle opzioni del blocco di codice (#| label: tbl-... e #| tbl-cap: "...").

Esercizi

Parte 1: Un report statico

Crea il documento report_biblioteche.qmd (File → New File → Quarto Document) e cancella il contenuto di esempio. Nell’intestazione YAML inserisci il titolo “Il sistema bibliotecario cittadino”, un sottotitolo, il tuo nome come autore, la data del rendering (today) in formato “giorno mese anno” e la lingua italiana

Suggerimento

Il formato della data si imposta con date-format, ad esempio "D MMMM YYYY"; la lingua con lang: it, che traduce anche le parole generate da Quarto (“Figura”, “Tabella”, “Indice”, …).

Imposta nello YAML due formati di output:
- html, con indice, sezioni numerate, un tema a tua scelta, il codice “piegato” (code-fold) e tutte le risorse incluse in un unico file (embed-resources)
- typst, con indice, sezioni numerate, formato A4 e margini di 2.5 cm
Imposta inoltre, con un’unica opzione valida per tutti i blocchi di codice, che il codice non venga mostrato e che avvertimenti e messaggi vengano nascosti

Suggerimento

Le opzioni comuni a tutti i blocchi si indicano sotto execute:. Ricorda che lo YAML è sensibile ai rientri: le opzioni di un formato vanno rientrate di due spazi sotto il nome del formato, che a sua volta è rientrato sotto format:.

Inserisci all’inizio del documento un blocco di codice di setup che carica i package necessari (compreso knitr) e prepara le tabelle con il codice seguente, aggiungendo la tabella prestiti_validi con i soli prestiti per cui il genere letterario non è mancante. Il blocco non deve mostrare nulla nel documento finale

Codice per ricostruire le tabelle dell’esercitazione 1

library(tidyverse)
library(readxl)
library(janitor)

utenti <- read_delim("dati/utenti.csv", delim = ";") |>
  clean_names() |>
  mutate(
    categoria = replace_values(categoria, "stu" ~ "STU"),
    categoria = recode_values(categoria,
                              "STU" ~ "Studente",
                              "LAV" ~ "Lavoratore",
                              "PEN" ~ "Pensionato",
                              "DOC" ~ "Docente",
                              "ALT" ~ "Altro"),
    genere = replace_values(genere, "f" ~ "F"),
    genere = factor(genere, levels = c("F", "M"),
                    labels = c("Femmina", "Maschio")),
    eta = 2025 - anno_di_nascita
  )

prestiti <- read_excel("dati/prestiti.xlsx", sheet = "Prestiti 2025", skip = 3) |>
  clean_names()

catalogo <- read_tsv("dati/catalogo.txt") |>
  clean_names() |>
  rename(genere_letterario = genere)

prestiti_completo <- prestiti |>
  inner_join(utenti, by = join_by(cod_utente == id_utente)) |>
  left_join(catalogo, by = "inventario")

Scrivi una sezione “Introduzione” che presenti i dati e lo scopo del report. Nel testo usa almeno: una parola in grassetto, un elenco puntato con le tre tabelle di partenza, un link e una nota a piè di pagina. Aggiungi un blocco speciale (fenced div) di tipo callout-note, con un titolo, che spieghi perché i prestiti interbibliotecari non compaiono nell’analisi
Scrivi una sezione “Gli utenti”, con un’etichetta che permetta di citarla. Inserisci la tabella di frequenza degli utenti per categoria, ordinata dalla categoria più numerosa, con la riga dei totali e le percentuali, costruita con tabyl e formattata con kable. La tabella deve avere una didascalia ed essere citata nel testo con un riferimento incrociato. Riporta nel testo, con il codice inline, il numero di utenti e la loro età media

Suggerimento

Un’etichetta che inizia con tbl- rende la tabella numerabile: con #| label: tbl-categorie nel blocco di codice, nel testo @tbl-categorie diventa “Tabella 1”. Allo stesso modo, una sezione con ## Gli utenti {#sec-utenti} si cita con @sec-utenti. Il codice inline si scrive tra apici inversi, iniziando con r: ad esempio `r nrow(utenti)`. Per arrotondare un numero usa round.

Nella stessa sezione, inserisci il diagramma a barre orizzontali degli utenti per categoria (costruito con ggplot2), con una didascalia e un riferimento incrociato nel testo. Scegli larghezza e altezza del grafico in modo che risulti ben proporzionato nella pagina

Suggerimento

Una figura numerata ha un’etichetta che inizia con fig- e una didascalia: #| label: fig-categorie e #| fig-cap: "...". Le dimensioni si impostano con #| fig-width e #| fig-height, in pollici.

Scrivi una sezione “I prestiti” con:
- il grafico a linee del numero di prestiti per mese, con una linea per ciascuna biblioteca e tutti i mesi sull’asse orizzontale (ricorda il problema del mese di agosto incontrato nel compito precedente)
- la tabella della composizione dei prestiti per genere letterario in ciascuna categoria di utenti (profili riga, in percentuale), costruita con tabyl e adorn_* e formattata con kable
Grafico e tabella devono avere una didascalia ed essere citati nel testo con un riferimento incrociato
Aggiungi alla sezione “I prestiti” la formula della quota di prestiti prorogati (prestiti con proroga diviso prestiti totali), scritta come equazione su una riga a sé. Nella formula inserisci, con il codice inline, il numero di prestiti prorogati, il numero totale di prestiti e il valore della quota, arrotondato a tre cifre decimali

Suggerimento

Un’equazione su una riga a sé si scrive tra $$ e $$, con la sintassi di LaTeX: ad esempio \hat{p} = \frac{a}{b} produce una frazione. Il codice inline funziona anche all’interno di un’equazione. Il numero di prestiti prorogati si ottiene contando i valori "SI" della variabile proroga.

Crea nella cartella del progetto il file riferimenti.bib con le voci bibliografiche in formato BibTeX di due libri a tua scelta su R (ad esempio R for Data Science e ggplot2: Elegant Graphics for Data Analysis di Hadley Wickham), collega il file al documento nello YAML e cita i due libri nell’introduzione

Suggerimento

La voce BibTeX di un libro si ottiene da Google Scholar: cerca il titolo, clicca sull’icona delle virgolette e poi su “BibTeX”, e copia il testo nel file riferimenti.bib (un file di testo, che puoi creare con File → New File → Text File). Nel documento il file si collega con bibliography: riferimenti.bib; un libro si cita con @chiave o [@chiave], dove la chiave è la prima parola dopo la parentesi graffa, ad esempio wickham2023r. La bibliografia viene aggiunta automaticamente in fondo al documento.

Produci il report in entrambi i formati. Aggiungi in fondo al report una sezione “Osservazioni sul rendering” in cui descrivi almeno tre differenze tra la versione html e la versione pdf

Suggerimento

Il pulsante Render produce il primo formato indicato nello YAML; dal menu accanto al pulsante puoi scegliere l’altro. In alternativa, nel Terminale (non nella console di R) il comando quarto render report_biblioteche.qmd produce entrambi i formati.

Parte 2: Un controllo interattivo con OJS

Aggiungi al report, solo nella versione html, una versione interattiva del grafico a linee del punto 7: un menu a tendina permette di scegliere la biblioteca da mostrare, con l’opzione “Tutte” come valore di default. Scrivi il codice OJS con l’aiuto di un LLM a tua scelta (ChatGPT, Copilot, Claude, Gemini, DeepSeek, Kimi, …) e riporta il prompt utilizzato in un callout chiuso per default. Sotto il callout, descrivi brevemente se il codice ricevuto ha funzionato al primo tentativo e che cosa hai dovuto correggere o chiedere di nuovo

Suggerimento

Un contenuto visibile solo in html si racchiude in un blocco ::: {.content-visible when-format="html"} … :::
Un callout chiuso per default si ottiene con ::: {.callout-tip collapse="true"}
Nel prompt, ricordati di indicare il contesto (documento Quarto in html), il nome e le colonne della tabella da rappresentare, il comportamento atteso, il valore di default e i vincoli: i dati vanno passati da R a OJS con ojs_define(), il grafico va disegnato con Observable Plot, senza usare Shiny
Per verificare il funzionamento dei controlli apri il report con Render o con quarto preview nel Terminale: aprendo il file html con un doppio clic il browser potrebbe bloccare il codice OJS

Parte 3: Un report parametrico

Crea il documento report_biblioteca.qmd, un report parametrico per una singola biblioteca, con il parametro biblioteca (valore di default "B01") e i formati html e typst. Il titolo del report deve contenere il codice della biblioteca. Il report deve contenere:
- nel testo, calcolati con il codice inline: il numero di prestiti della biblioteca, la sua quota sul totale dei prestiti del sistema e il numero di utenti diversi che hanno preso un libro in prestito
- il diagramma a barre del numero di prestiti per mese, con una didascalia che contiene il codice della biblioteca
- la tabella dei prestiti per categoria di utente e la tabella dei generi letterari più prestati, formattate con kable

Suggerimento

I parametri si dichiarano nello YAML:

params:
  biblioteca: "B01"

e nel codice si usano come params$biblioteca, ad esempio per filtrare i prestiti: filter(biblioteca == params$biblioteca). Nel titolo il parametro si inserisce con il codice inline: title: "Report della biblioteca `r params$biblioteca`". Una didascalia che dipende da un parametro si scrive con !expr: #| fig-cap: !expr paste("Prestiti per mese nella biblioteca", params$biblioteca).

Aggiungi al blocco di setup del report parametrico un controllo che interrompa il rendering con un errore se il parametro non corrisponde a una delle quattro biblioteche. Prova a produrre il report per la biblioteca "B05", prima e dopo aver aggiunto il controllo, e descrivi in un commento nello script genera_report.R che cosa succede nei due casi

Suggerimento

La funzione stopifnot(condizione) interrompe l’esecuzione con un errore se la condizione è falsa. L’operatore %in% verifica se un valore appartiene a un vettore.

Crea lo script genera_report.R e, con la funzione quarto_render del package quarto, produci il report html della biblioteca B02 nel file report_B02.html

Suggerimento

quarto_render("nome_documento.qmd",
              execute_params = list(parametro = valore),
              output_file = "nome_del_file.html",
              output_format = "html")

Nello stesso script, usa la funzione walk del package purrr per produrre automaticamente i report html di tutte e quattro le biblioteche, nei file report_B01.html, report_B02.html, report_B03.html e report_B04.html

Suggerimento

walk(vettore, funzione) applica la funzione a ciascun elemento del vettore. La funzione si può scrivere direttamente, come funzione anonima: walk(biblioteche, \(x) quarto_render(...)), dove x assume uno dopo l’altro i valori di biblioteche. Il nome di ciascun file si costruisce con paste0.

Con walk produci anche le versioni pdf dei quattro report, nei file report_B01.pdf, …, report_B04.pdf. Poi costruisci con la funzione map_chr il vettore dei nomi dei quattro file pdf e verifica con map_lgl e la funzione file.exists che tutti i file siano stati creati. Spiega in un commento la differenza tra map e walk, e perché per produrre i report si usa walk

Suggerimento

Per il pdf basta indicare output_format = "typst". Le funzioni map_chr, map_dbl, map_lgl sono varianti di map che restituiscono un vettore di un tipo preciso (stringhe, numeri, valori logici) invece di una lista.

★ (facoltativo) Aggiungi al report parametrico un secondo parametro, ad esempio la categoria di utenti, con valore di default "Tutte", e produci con un ciclo i report di una biblioteca per ciascuna categoria. In alternativa, aggiungi al report statico della Parte 2 un secondo controllo interattivo, ad esempio caselle di controllo per scegliere le biblioteche da confrontare

Consegna

Per inviare la tua soluzione carica su Teams, in risposta al compito assegnato, un file hw07_cognome_nome.zip con il contenuto della cartella del progetto:

i file report_biblioteche.qmd, report_biblioteca.qmd, genera_report.R e riferimenti.bib
i report prodotti: report_biblioteche.html, report_biblioteche.pdf e i report html e pdf delle quattro biblioteche
la cartella dati

Valutazione

Totale punti disponibili: 110 punti

Component	Punti
Es 1 - 16	100
Es 17 (facoltativo)	-
Workflow & formattazione	10¹

Footnotes

La valutazione al “Workflow & formattazione” tiene conto del rispetto delle regole di stile e del principio di riproducibilità: i documenti e lo script consegnati devono funzionare senza errori su qualunque PC, con i file dei dati nella sottocartella dati del progetto, dando gli stessi risultati↩︎