14  Elements de Quarto

14.1 Introducció

La imatge que hauríem de veure a la nostra pantalla hauria de ser molt semblant a la següent. Fixem-nos bé en els tres elements principals de Quarto, que hem destacat a la imatge següent:

  • YAML: Conté les metadades del document.
  • Chunk: Conté codis d’R.
  • Text: Conté el text.

Com hem vist anteriorment, la icona assenyalada a la imatge amb quadre vermell obre l’Html al navegador d’internet que tenim configurat per defecte.

Si observem amb atenció el document de Quarto i el comparem amb l’Html que acabem de generar, veurem que el YAML conté elements com el títol o la data. També observem que el símbol # sembla marcar els apartats del document. I també veiem que, curiosament, el chunk no apareix a l’Html. A continuació explicarem amb detall aquests tres elements: YAML, text i chunk.

Exercici 14.1 (Explora el tutorial) Compara l’arxiu NMC_cat.qmd i el seu resultat amb el document d’Html, de manera que puguis anar veient com els elements de Quarto queden reflectits en l’Html. Prova de fer algun canvi en el text. Prem el botó Render per veure els canvis reflectits a l’Html. Si en algun punt et dona error, torna enrere o prova de descarregar-te el tutorial de nou.

14.2 YAML

La primera part d’un document de Quarto es diu YAML. El seu inici i el seu final estan delimitats amb una línia de codi amb tres guions ---. En el YAML hi podem posar diferents tipus d’informació:

  • Informació general que apareixerà a l’encapçalament del document com el títol, l’autoria i la data.
  • Indicacions sobre el format amb què es reproduirà el document: Html, Pdf o Word.
  • Altres qüestions relacionades amb el format del document. Per exemple, si escollim generar un document Html, podem:
    • Enumerar-ne les seccions (number-sections: true).
    • Posar una taula de continguts (toc: true).
    • Fer que la taula de continguts tingui una profunditat de fins a tres subapartats (number-depth: 3).

El YAML té altres funcionalitats que coneixerem més endavant a la subsecció de YAML avançat.

Exercici 14.2 (Canvis en el YAML) Fes els següents canvis en el YAML del document NMC_cat.qmd.

  • Canvia el nom, el títol i la data.
  • Afegeix una línia nova i introdueix theme: cyborg.

Per visualitzar com queden els canvis que hem fet al document de Quarto, haurem de fer Render per tal que ens torni a generar un Html nou.

14.3 Text

Com s’ha explicat anteriorment, la gran virtud de Quarto és intercalar text i codi d’R. El text es pot inserir a qualsevol línia de codi per sota del YAML i per defecte es reproduirà en lletra rodona. A continuació es detallen els elements més importants per canviar el format del text:

  • Si volem fer servir negretes, envoltarem el text amb dos asteriscos (**text**).
  • Si volem fer servir cursives, envoltarem el text amb un asterisc (*text*) o bé amb un guió baix (_text_).
  • Si volem posar lletra de codi, envoltarem el text amb dos accents oberts (`text`).
  • Si volem afegir un enllaç web, posarem el nom del text entre claudàtors seguit de la direcció de l’enllaç entre parèntesis ([Web](https://www.jordimas.cat/)).
  • Si volem afegir una nota al peu1, posarem el text entre claudàtors i el precedirem per un símbol d’intercalació (^[Nota al peu]).

  • 1 Això és una nota al peu.

    • Els títols de secció es marquen de la següent manera:

    # Títol de secció

## Títol de subsecció

### Títol de subsubsecció

    Si volem crear llistes, deixarem una línia de codi de marge entre el text i el primer ítem de la llista, que començarem amb *, - o +. Podem crear subnivells si afegim quatre espais:

    - primer ítem
- segon ítem
- tercer ítem
    - primer subítem
    - segon subítem
    - tercer subítem

    Al document d’Html apareixerà de la següent manera:

    • primer ítem
    • segon ítem
    • tercer ítem
      • primer subítem
      • segon subítem
      • tercer subítem

    Les llistes també poden començar amb nombres:

    1. primer ítem
2. segon ítem
3. tercer ítem
    - primer subítem
    - segon subítem
    - tercer subítem

    Al document d’Html apareixerà de la següent manera:

    1. primer ítem
    2. segon ítem
    3. tercer ítem
      • primer subítem
      • segon subítem
      • tercer subítem

    Hi ha més possibilitats d’edició de text, que podeu consultar a Markdown Basics.

    Exercici 14.3 (Canvis en el text) Llegeix atentament el primer apartat (Introducció) del document tutorial. Prova de crear:

    • Un text amb cursiva.
    • Un amb negreta.
    • Un enllaç a una pàgina web.
    • Una llista amb dos ítems.

    Per visualitzar com queden aquests canvis, hauràs de fer Render per tal que ens torni a generar un Html nou.

    14.4 Chunks

    Els chunks permeten afegir codi d’R document al de Quarto. Normalment, utilitzarem aquest codi per afegir taules o gràfics. Per crear chunks nous:

    • Premem Ctrl + Alt + I (Mac: Cmd + Option + I).
    • O, alternativament, podem simplement copiar i enganxar un chunk que ja estigui creat i modificar-ne el seu contingut.

    Els chunks tenen aquesta forma:

    ```{r}

```

    Com podem observar, els chunks tenen els elements següents:

    • ```{r}: L’inici del chunk està marcat per tres accents oberts i la lletra r, que indica que a dins el chunk hi haurà codi d’R.
    • Al mig del chunk, en blanc a la imatge, és on insertarem el codi d’R.
    • ```: El final del chunk està marcat per tres accents oberts.

    Opcionalment, a la dreta de la lletra r, després d’un espai de separació, hi podem donar dos tipus d’indicacions:

    • L’etiqueta del chunk. Per exemple, ```{r prova}. Si hi volem posar més d’una paraula, idealment utilitzarem el guionet com a separador: ```{r grafic-barres}. En un mateix document de Quarto, no hi pot haver dos chunks amb una mateixa etiqueta.
    • Els elements del codi que volem que es visualitzin a l’Html. Aquesta taula 14.1 és una taula resum de les principals especificacions que podem posar al chunk.
    Taula 14.1: Especificacions als chunks
    Ordre Opció defecte Què fa?
    message TRUE Mostra els missatges que ens apareixerien a la consola.
    warning TRUE Mostra els avisos que ens apareixerien a la consola.
    echo TRUE Amaga el codi chunk.
    eval TRUE Reprodueix el chunk.
    include TRUE Mostra tots els elements.

    Quan vulguem incloure algun d’aquests elements, sempre posarem un espai entre la r i el primer element. I, a partir del segon element, separarem tots els altres elements amb una coma. Per exemple, al chunk següent li hem posat com a etiqueta prova i li diem que a l’Html que ens generi volem veure el codi (echo = TRUE), volem veure també el resultat del codi (eval = TRUE) i que amagui els missatges que apareguin a la consola.

    ```{r prova, echo = TRUE, eval = TRUE, message = FALSE, collapse=T}
plot(datasets::co2)
```

    A continuació, observem com es reprodueix aquest chunk que hem anomenat prova en un Html de Quarto. Fixem-nos en tres detalls:

    • Primer veiem el codi de dins el chunk, perquè hem indicat l’opció echo = TRUE.
    • Després veiem el gràfic, perquè hem indicat l’opció eval = TRUE.
    • Si l’operació ens genera algun missatge a la consola, aquest missatge quedarà amagat a l’Html perquè hem indicat message = FALSE.
    plot(datasets::co2)

    Exercici 14.4 (Canvis en el codi) Llegeix el tercer apartat (Chunks) del tutorial NMC_cat.qmd i fes els canvis en els chunks que se’t proposen.

    Per visualitzar com queden els canvis que hem fet al document de Quarto, haurem de prémer el botó Render per tal que ens torni a generar un Html nou.

    Errors de Render

    Els errors més comuns que es produeixen en treballar amb Quarto són a conseqüència de confondre les funcionalitats Render i de l’R Script. Les dues principals fonts d’error són:

    • Utilitzem funcions o objectes que no hem carregat o creat en chunks anteriors. Potser els tindrem a l’Environment, però no estaran carregats o creats a cap dels chunks.
    • Utilitzem funcions o objectes que tenim creats anteriorment, però el chunk en qüestió està en eval = FALSE.

    Tampoc s’han de posar mai les funcions install.packages() i View() dins dels chunks de Quarto. Donarà error quan renderitzem.

    Arribats a aquest punt, és molt important saber diferenciar molt clarament les dues funcionalitats del document de Quarto. Podem fer servir el document Quarto com una plantilla que ens generarà un document d’Html, PDF o Word quan pitgem Render (a); o el podem utilitzar com un R Script (b).

    1. Opció Render: Perquè un document de Quarto es reprodueixi correctament quan renderitzem, hem de pensar que Render funciona de forma autònoma al Global Environment. Això significa que per generar un output de Quarto tots els objectes, funcions i paquets que utilitzem han d’estar indicats de manera seqüencial (de dalt a baix) en els chunks del document. Després de pitjar el botó Render, R començarà a llegir el primer chunk, després el segon chunk, i així successivament. Si es troba amb un chunk en què s’utilitza una funció o un objecte que no hem carregat o creat expressament i amb anterioritat, la renderització no es completarà i ens apareixerà un missatge d’error. Per tant, serà recomanable carregar els paquets i importar els arxius i transformar-los en objecte en els primers chunks del document.

    2. Opció Script d’R: Alternativament, podem utilitzar Quarto com un R Script normal, creant objectes i carregant funcions al Global Environment mitjançant Ctrl+Enter. No obstant això, haurem de tenir en compte que tot allò que haguem carregat a l’Environment no tindrà cap efecte a l’hora de renderitzar.