---
title: "`Quarto`: un sistema di pubblicazione scientifica e tecnica open source"
author: "Domenico Vistocco"
format: 
  html:
    page-layout: full
    toc: true
    toc-title: INDICE
    toc-location: right
execute: 
  eval: true
  echo: true
  message: true
  warning: true
---

## 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:

![](figures/rstudio-qmd-how-it-works.png)

Un report Quarto si compone di due sezioni:

-   la sezione `YAML` (`Y`et `A`nother `M`arkup `L`anguage), 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](https://quarto.org/docs/authoring/markdown-basics.html), mentre la [documentazione ufficiale di `Quarto`](https://quarto.org/docs/guide/) 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`](https://quarto.org/docs/get-started/hello/rstudio.html)

2.  [Computations](https://quarto.org/docs/get-started/computations/rstudio.html)

3.  [Authoring](https://quarto.org/docs/get-started/authoring/rstudio.html)

### 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](https://quarto.org/docs/output-formats/html-themes.html) 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:

-   [Online LaTeX equation editor](https://latex.codecogs.com/eqneditor/editor.php)

-   [LaTeX equation editor](https://latexeditor.lagrida.com/)

-   [TutorialsPoint LaTeX equation editor](https://www.tutorialspoint.com/latex_equation_editor.htm)

-   [LaTeX4technics equation editor](https://www.latex4technics.com/)

-   [HostMath equation editor](https://www.hostmath.com/)

-   [Equation editor for online Mathematics](https://www.codecogs.com/eqnedit.php)

-   [SciWeavers LaTeX equation editor](http://www.sciweavers.org/free-online-latex-equation-editor)

### 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`):

-   [Tables Generator](https://www.tablesgenerator.com/markdown_tables)

-   [Markdown Table Editor and Generator](https://tableconvert.com/markdown-generator)

-   [Markdown Table Generator](https://tabletomarkdown.com/generate-markdown-table/)

## Un esempio di report con codice `R` integrato

Puoi visualizzare su [questo link](lab_12-quarto-tutorial/lab_12-report-quarto_codice-integrato.html) 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](lab_12-quarto-tutorial/lab_12-report-quarto_codice-esterno.html) un esempio di report `Quarto` con codice esterno.

## Un esempio di report parametrico

Puoi visualizzare:

- su [questo link](lab_12-quarto-tutorial/lab_12-report-quarto-parametrico_codice-integrato.html) un esempio di report `Quarto` parametrico con codice `R` integrato,

- su [questo link](lab_12-quarto-tutorial/lab_12-report-quarto-parametrico_codice-esterno.html) 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`:

```{r}
#| echo: true
#| eval: false
quarto::quarto_render(input = "lab_12-report-quarto-parametrico_codice-integrato.R")
```

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

```{r}
#| echo: true
#| eval: false
quarto::quarto_render(input = "lab_12-report-quarto-parametrico_codice-integrato.R", 
                      execute_params = list(continente = "Europe"))
```


```{r}
#| echo: true
#| eval: false
quarto::quarto_render(input = "lab_12-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:
```{r}
#| echo: true
#| eval: false
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_12-report-quarto-parametrico_codice-integrato.R",
                execute_params = list(continente = x),
                output_file = paste0("report_", x, ".html"))
            })
```
