Quarto

Quarto è un sistema per scrivere documenti che contengono il codice che li produce. Nello stesso file stanno il testo, l'analisi e i grafici; da lì esce un PDF, una pagina web, un documento Word o una presentazione. È l'evoluzione di R Markdown e funziona con R, Python e altri linguaggi.

Il problema che risolve

Il report trimestrale in cui qualcuno rifà le stesse tabelle, le incolla in Word, aggiorna i numeri nel testo e dimentica una percentuale in fondo alla pagina. Con Quarto quel numero nel testo non si scrive a mano: si prende dal calcolo. Se cambia il dato, cambia ovunque, e non esiste la versione in cui la tabella dice una cosa e il paragrafo un'altra.

Il parametro, che è la parte che fa la differenza

Un documento può avere parametri, per esempio la filiale, l'azienda sanitaria o il trimestre. Lo stesso file genera dodici report diversi lanciando un comando invece di dodici copie da aggiornare a mano. Chi ogni tre mesi rifà gli stessi documenti per sedi o aziende diverse recupera giornate intere.

Un esempio: lo stesso report per ogni filiale

In testa al documento si dichiarano i parametri con un valore predefinito:

---
title: "Report trimestrale"
format: html
params:
  branch: "Milano"
  quarter: "2025-Q3"
---

Nel corpo il codice li usa, e il numero nel testo viene dal calcolo, non dalla tastiera. Qui read_sales() sta per la funzione che legge i vostri dati:

```{r}
sales <- read_sales(params$branch, params$quarter)
```

Nel trimestre la filiale ha registrato `r nrow(sales)` vendite.

Per generare un report per ogni filiale basta un ciclo, da R, oppure lo stesso comando da terminale con l'opzione -P:

for (b in c("Milano", "Torino", "Bologna")) {
  quarto::quarto_render(
    "report.qmd",
    execute_params = list(branch = b, quarter = "2025-Q3"),
    output_file    = paste0("report-", b, ".html")
  )
}

Il risultato sono tre file, uno per sede, tutti dallo stesso sorgente. Aggiungere una filiale significa aggiungere un nome all'elenco.

Cosa consegna

PDF per l'invio formale, HTML per il cruscotto consultabile, Word quando il destinatario deve poter modificare. Lo stesso contenuto, tre formati, nessuna riscrittura.

Gli errori che si fanno tutti

• I numeri scritti a mano nel testo. Basta una cifra copiata dall'output invece che calcolata, e il documento torna a poter dire due cose diverse. Ogni numero nel testo dovrebbe venire da codice in linea.
• Il PDF che non esce. Per il PDF serve una distribuzione LaTeX. La più leggera si installa con quarto install tinytex; senza, Quarto produce HTML e Word ma si ferma sul PDF.
• I percorsi dei file. Il documento viene eseguito dalla propria cartella: un percorso che funziona nella console può non funzionare durante la generazione. Conviene lavorare per progetti e usare percorsi relativi.
• La cache dimenticata. Con la cache attiva, i blocchi già calcolati non vengono rieseguiti: se i dati cambiano senza che cambi il codice, il report può mostrare risultati vecchi.

Il punto delicato: chi lo riceve

Il PDF non si commenta facilmente e il Word viene subito modificato da qualcuno, rompendo la riproducibilità. Vale la pena decidere in anticipo quale formato è il documento ufficiale e quali sono solo copie, altrimenti dopo due giri non si sa più quale versione faccia fede.

In azienda

Non richiede permessi particolari oltre a quelli di R o Python, ma per produrre PDF serve una catena di composizione tipografica che va installata una volta sola. Dove non è possibile, l'HTML è l'alternativa che non chiede niente a nessuno.

Dove si prende

Quarto è gratuito e open source, si scarica da quarto.org per Windows, macOS e Linux. Le versioni recenti di RStudio lo includono già. Da R il pacchetto quarto permette di lanciare la generazione dagli script, come nel ciclo sopra.

Per imparare

La guida ufficiale, ordinata per formato di uscita. La pagina sui parametri per i report in serie. Il capitolo su Quarto di R for Data Science, gratuito online.

Quando ha senso impararlo

Se producete lo stesso documento più di due volte l'anno. Sotto quella soglia non si ripaga, sopra diventa difficile tornare indietro.