2  Documentos

En este capítulo se detallan algunas características de los dos documentos que intervienen en el proceso de publicación: el documento fuente de Quarto y el documento de salida.

2.1 Documento Fuente de Quarto

La escritura de un reporte, artículo, libro, etc., comienza con un documento fuente de Quarto (.qmd)1. Este documento contiene toda la información para generar el documento de salida.

2.1.1 Componentes del Documento Quarto

Los documentos de Quarto pueden incluir tres tipos de contenidos:

  1. Encabezado YAML (sección 2.1.1.1)

  2. Fragmentos de código (sección 2.1.1.2)

  3. Texto (sección 2.1.1.3)

2.1.1.1 Encabezado YAML

Constituye una especie de apartado de configuración. Allí pueden incluirse opciones que determinan el formato de salida, la manera en la que se ejecuta el código y el método de presentación de las referencias bibliográficas, entre otros. Además puede contener metadatos como el título, el autor y la fecha. Este encabezado usa el lenguaje YAML (YAML Ain’t Markup Language).

Aunque el encabezado YAML es optativo, bajo ciertas circunstancias se genera automáticamente durante el proceso de renderizado que genera el archivo de salida (cf. sección 2.2.1).

El YAML encabeza el documento Quarto; de ahí su nombre. Tanto el inicio como la finalización del encabezado YAML están definidos por tres guiones aislados en una línea. Al interior, cada uno de los elementos de configuración o metadados ocupa una línea.

Un encabezado YAML podría tener el siguiente aspecto:

---
title: RESPUESTA FISIOLÓGICA
subtitle: Estrés fisiológico
author: Luz Marina Bilbao
date: 09-20-23
lang: es
format: html
---


Para definir los metadatos o las opciones se usa la sintaxis clave: valor. En el anterior encabezado, la primera palabra de cada línea es una clave, mientras que la información que aparece a continuación de los dos puntos es su valor. Así, por ejemplo, title es una clave, cuyo valor para el presente ejemplo es RESPUESTA FISIOLÓGICA.

Las claves de metadatos más comunes son title, subtitle, author y date. Las claves title, subtitle y author admiten como valor cualquier cadena de caracteres, en la que pueden incluirse espacios y caracteres especiales, sin que sea necesario encerrar la cadena entre comillas, aunque funciona exactamente igual si se escribe entrecomillada.

¡No pierda la noción del tiempo!

Aunque la definición de la fecha debería ser un asunto poco trascendental, hay algunos aspectos que deben tenerse presentes para obtener el resultado que se tiene en mente:

  • Los valores para la clave date deben presentarse en formato mes-día-año (o mes/día/año).

  • Los valores de año pueden presentarse con 2 o con 4 cifras. Debe tenerse presente, sin embargo, que, cuando se usan dos cifras se asume que se hace referencia a un año del siglo xxi. Así, si se escribe, por ejemplo, 12-15-97, el sistema toma 97 como 2097. Si lo que se tenía en mente era 1997, deberá escribirse el año completo: 12-15-1997.

  • Cuando se escribe un número de 4 cifras al comienzo del valor para date, el sistema interpreta que se trata del año, con lo cual interpreta los tres elementos como año-mes-día.

  • Si —por error— se usa un valor mayor de 12 para el mes, cada múltiplo de 12 se toma como un año y se le suma al correspondiente valor, dejando el residuo como el mes. Así, por ejemplo, al escribir 13-20-25, el valor 13 se interpreta como un año + 1 mes, lo que internamente se traduce como 01-20-26. Si se escribiera 26-20-25, se interpretaría como 02-20-27.

La clave lang define tanto el lenguaje como algunos otros aspectos de la presentación de los metadatos. El lenguaje por defecto es inglés. Si se desea usar el español, debe especificarse, mediante el par lang: es.

Entre los aspectos más notorios de cambiar el lenguaje de inglés al español están que, en lugar de AUTHOR, aparece AUTOR/A; en lugar de PUBLISHED aparece FECHA DE PUBLICACIÓN; en lugar de presentar la fecha en formato ‘September 20, 2023’, se presenta como ‘20 de septiembre de 2023’.

El formato por defecto para documento de salida es html (format: html), por lo que no haría falta especificarlo si este fuera el formato deseado. En su lugar, pueden usarse los valores pdf o docx para generar documentos en pdf o Word, respectivamente.

A continuación se presentan algunas variantes sobre el encabezado YAML que se analizó anteriormente:

---
title: RESPUESTA FISIOLÓGICA
subtitle: Estrés fisiológico
author:
  - Luz Marina Bilbao # Autor para correspondencia
  - Alejandro Piedrahíta
date: 09-20-23
lang: es
format:
  html:
    embed-resources: true
---

La clave author admite múltiples valores (para múltiples autores). En este caso, los autores se presentan mediante una lista, debajo de la clave. Cada autor va antecedido de un guion y al menos un espacio. La lista de autores está indentada con respecto a la clave author. Puede usarse cualquier número de espacios para la indentación (lo usual son 2 espacios), pero debe ser el mismo para los diferentes autores.

Los encabezados YAML admiten comentarios, al igual que los scripts clásicos de R, bien sea al frente de una entrada o en línea completa. Para introducir un comentario se usa el símbolo # (cf. R paso a paso: Comentarios).

Una cadena de caracteres puede actuar como clave y como valor. En estos casos se usan diferentes niveles de indentación. Así, por ejemplo, al analizar las tres últimas líneas del anterior encabezado, se observa que html es el valor de la clave format. No obstante, dado que se realizan especificaciones adicionales sobre este formato, no puede escribirse simplemente format: html, como en el primer ejemplo de encabezado YAML, en cuyo caso, se aplicaría el formato htlm, con todos sus valores por defecto. Los dos puntos que aparecen después de html indican que hay especificaciones adicionales para el formato htlm.

Las especificaciones adicionales para el documento htlm se incluyen debajo de html` con una indentación. Así, por ejemplo, para especificar la manera en la que almacenan los recursos, se incluye la opción embeded-resources, con su correspondiente valor, tal y como se ilustra en la última línea del encabezado anterior.

Mejor solo…

La salida html que se genera por defecto —bien sea que se especifique en el YAML o que no se haga— corresponde a un archivo con extensión html y una carpeta acompañante con los recursos.

El archivo y la carpeta son inseparables: si se mueve cualquiera de los dos a una nueva ubicación, el otro lo acompañará y lo mismo sucede si se borra cualquiera de los dos.

Este ‘pareamiento’ falla, sin embargo, cuando se anexa el archivo html a un correo electrónico. Si no se incluye la carpeta con los recursos, la información llegará incompleta y el archivo que reciba el destinatario no podrá acceder a los recursos necesarios.

Aunque no se tenga intención de compartir la información por correo, resulta más cómodo tener todos los recursos incorporados en un solo archivo, en lugar de tenerlos en una carpeta acompañante.

Para hacer que la salidas html consten de un único archivo con todos los recursos incorporados, debe agregársele una opción al formato html, así:

---
format:
  html:
    embed-resources: true
---
Precaución 2.1: ¡Preste atención a los booleanos!

Los valores de algunas claves deben especificarse mediante un booleano (falso o verdadero). Los usuarios de R pueden verse tentados a usar los valores F y T. Estos valores, sin embargo, no son reconocidos en el encabezado YAML. Los valores booleanos correctos son false y true.

Para revisar con mayor detalle lo referente al encabezado YAML y sus diferentes opciones, lo invitamos a revisar la publicación de Greg Martin en RPubs.

2.1.1.2 Fragmentos de código

Un fragmento de código es justo lo que su nombre indica: una instrucción o conjunto de instrucciones codificadas en algún lenguaje de programación. Quarto admite fragmentos de código en diferentes lenguajes, entre los que se destacan R, Python, Julia y Observable JS. Lógicamente, sería necesario tener instalados los correspondientes intérpretes (o entornos de ejecución) para poder procesar el código.

Cada fragmento de código debe iniciarse con tres comillas invertidas seguidas de un par de llaves con una cadena de caracteres que identifica el lenguaje; para el caso de R, se usa la letra r. El fragmento finaliza con tres comillas invertidas aisladas en una línea. Todas las instrucciones incorporadas entre la línea de inicio y la de finalización constituyen un bloque de código o fragmento de código (code chunk). Los fragmentos de código tienen las mismas características que el código de los scripts clásicos del correspondiente lenguaje.

Un fragmento de código R tendría el siguiente aspecto:

```{r}
x <- c(4.1, 6.5, 4.8, 3.5, 2.7, 3.0, 5.9, 2.3)
var(x)
```

Este fragmento de código, además de crear el vector x, que podría usarse posteriormente en algún otro fragmento, genera un resultado:

[1] 2.322857

Para facilitar la creación de un nuevo fragmento de código, puede usarse la combinación de teclas (o el ícono Insert a new code chunk ), con lo cual se incluye un fragmento de código vacío en el documento.

```{r}

```

El documento Quarto puede incluir tantos fragmentos de código como sean necesarios.

2.1.1.2.1 Opciones de los fragmentos de código

Los fragmentos de código pueden incluir opciones, de manera análoga a los argumentos de las funciones de R, pero, a diferencia de los argumentos de las funciones (que aplican únicamente a una función particular en una invocación específica) las opciones de los fragmentos de código aplican a todo el fragmento.

Se trata de opciones generales, como el nombre del fragmento, si se ejecuta o no y si su contenido se muestra en el documento final (cf. sección 2.2.2). A diferencia de los argumentos de las funciones —algunos de los cuales son obligatorios— todas las opciones de los fragmentos de código son optativas.

Cuando un fragmento de código incluye opciones, estas inician con los símbolos #| y manejan la misma sintaxis de las opciones del encabezado YAML, es decir, clave: valor.

Un fragmento de código R con opciones tendría el siguiente aspecto:

```{r}
#| label: Carga de paquetes
#| include: false

library(MASS)
library(car)
library(agricolae)
```
Reglas para definir las opciones de los fragmentos de código

Al escribir las opciones de los fragmentos de código deben atenderse una serie de reglas:

  1. Las opciones deben aparecer en la primera línea del fragmento y posteriores, sin que medie ningún código ejecutable, comentario ni espacio entre ellas. Cada opción ocupa una línea.

  2. La etiqueta indicadora de las opciones de fragmento de código #| debe iniciar en la primera columna, sin que la anteceda ningún espacio.

  3. Después de la etiqueta #| es necesario dejar exactamente un espacio.

  4. Los dos puntos van pegados de la clave, sin dejar ningún espacio de separación (v. gr., include:).

  5. Debe dejarse al menos un espacio entre los dos puntos y el valor (v. gr., include: false).

  6. Los posibles valores de las claves lógicas o booleanas son false y true.

Una de las posibles opciones de los fragmentos de código es un nombre o etiqueta de identificación (label), el cual puede constar de una o más palabras, sin que sea necesario entrecomillarlas. No obstante, en caso de optar por la inclusión de etiquetas, estas deben ser únicas.

```{r}
#| label: resumen del análisis de varianza
summary(anova)
```
¡Atención a la unicidad!

Dos o más fragmentos de código no pueden tener el mismo nombre.

Cuando no se asignan etiquetas a los fragmentos de código, estos reciben internamente un identificador genérico: chunk 5, chunk 6, chunk 7… Las etiquetas o nombres de los fragmentos pueden facilitar la navegación en documentos que contengan muchos fragmentos de código.

Para acceder al panel de navegación, se hace clic en la banda inferior de la ventana que contiene el documento Quarto.

¿Deben etiquetarse los fragmentos de código?

Si bien es cierto que la asignación de etiquetas a los diferentes fragmentos de código puede facilitar la navegación a través de estos, también es cierto que su inclusión —así como la verificación de unicidad— puede exigir más tiempo del que eventualmente pudiera ganarse posteriormente. En tal sentido, cada usuario habrá de valorar cuál de estas opciones (inclusión u omisión de etiquetas) le brinda mayores beneficios.

En adición debe tenerse presente que estos marcadores de navegación, que son equivalentes a los manejados en los scripts clásicos de R (cf. R paso a paso: Comentarios), si bien resultaban muy útiles en aquellos, no lo son tanto en los documentos de Quarto, en los que se cuenta con marcadores de navegación más prácticos a través de los títulos (cf. sección 2.1.1.3.1).

Quizá una estrategia intermedia resulte práctica: etiquetar únicamente aquellos fragmentos que sean muy importantes y a los que se quiera acceder posteriormente de manera rápida.

Algunas opciones de los fragmentos de código pueden establecerse de manera global en el encabezado YAML, de manera que afecten a todos los fragmentos de código (cf. sección 2.2.2). No obstante, las opciones particulares de cada fragmento tienen prioridad sobre las opciones globales.

2.1.1.2.2 Comentarios dentro de los fragmentos de código

Es posible incluir comentarios dentro de los fragmentos de código, mediante el uso del símbolo numeral (#). Al igual que en los scripts clásicos, tales comentarios se usarían como guía dentro del correspondiente fragmento o para desactivar temporalmente alguna instrucción sin borrarla (cf. R paso a paso: Comentarios). No obstante, para realizar comentarios más elaborados sobre algún procedimiento o resultado particular, con la intención de que tales comentarios aparezcan luego en el documento de salida, se usa el componente texto (sección 2.1.1.3).

2.1.1.3 Texto

El texto es el tercer tipo de contenido de los documentos Quarto. Cualquier contenido que no esté dentro de un fragmento de código ni forme parte del encabezado YAML se toma como texto y aparecerá como tal en el documento de salida.

¡Texto!

Aquí se usa texto en sentido amplio, considerando todos aquellos elementos que usualmente están presentes en un documento proveniente de un editor de textos tipo Word: el texto propiamente dicho, tablas, imágenes, ecuaciones…

Quarto procesa el texto usando el lenguaje de marcado ligero Markdown. Tales herramientas están incluidas en el paquete rmarkdown, el cual debe estar instalado.

Cuando se usa Quarto desde RStudio no es necesario instalar ni el paquete quarto para R ni el software Quarto para uso independiente, puesto que RStudio ya incluye Quarto2.

Mediante códigos de marcas es posible asignar formatos particulares al texto, los cuales se verán reflejados en el archivo de salida.

2.1.1.3.1 Títulos

Existen 6 niveles de títulos3, que se indican anteponiendo el correspondiente número de símbolos numeral (#) a la línea. El nivel 1 es el de mayor rango, mientras que el de nivel 6 es el de menor rango.


# TÍTULOS DE NIVEL 1

## TÍTULOS DE NIVEL 2

### TÍTULOS DE NIVEL 3

#### TÍTULOS DE NIVEL 4

##### TÍTULOS DE NIVEL 5

###### TÍTULOS DE NIVEL 6


¡Pueden nomenclarse!

En documentos estructurados, como los libros, los títulos actúan como marcadores de capítulos y secciones y pueden numerarse.

Para ello, es necesario incluir la opción number-sections: true en el YAML.

En tales casos, la nomenclatura se asigna automáticamente, acorde con su jerarquía.

La apariencia final de los títulos de cada nivel, en términos de color, tipo de letra, tamaño, negrilla, cursiva, etc., dependerá del tipo de documento de salida que se genere (Word, pdf, html).

Además de lo meramente estético, los títulos de diferentes niveles facilitan la navegabilidad dentro del documento final. Un ejemplo de ello se observa en salidas html, como la del presente libro, en las que los marcadores de título se usan para generar un menú por capítulos (que aparece en la parte izquierda cuando se visualiza desde un computador) y un submenú por secciones dentro de cada capítulo (que aparece en la parte derecha cuando se visuliza desde un computador). De manera análoga, los títulos generan paneles de navegación en documentos pdf y de Word4.

Asimismo, estos marcadores facilitan la navegabilidad dentro del documento fuente de Quarto. Para acceder al panel de marcadores, se presiona el ícono , que se ubica en la parte superior derecha del panel principal del documento fuente, o se presiona .

Igualmente, puede accederse a un panel de marcadores dentro del documento fuente de Quarto, haciendo clic en la banda que aparece en la parte inferior de la ventana que contiene el documento fuente de Quarto. En este caso, se despliega un panel de navegación más completo, que, además de los títulos, contiene los fragmentos de código.

¡Atención a los títulos!

Para que los títulos sean reconocidos como tal, es necesario que el símbolo o símbolos # aparezcan al inicio de la línea, sin dejar ningún espacio. Asimismo, es necesario dejar al menos un espacio entre los símbolos # y el título.

\(\;\,\)# Intento 1 de título (Incorrecto: hay un espacio antes del símbolo #)

#Intento 2 de título (Incorrecto: no hay espacio entre el símbolo # y la cadena de caracteres)

Símbolo #

Nótese que el símbolo # desemepeña un rol diferente dependiendo de si se encuentra ubicado dentro de un fragmento de código o si forma parte del texto.

Dentro de los encabezados YAML o de los fragmentos de código se usa para indicar que se trata de un comentario o de código que no se ejecuta (cf. R paso a paso: Comentarios).

También puede usarse junto con una pleca #| para introducir las opciones de los fragmentos de código (cf. sección 2.1.1.2.1).

Cuando aparece al inicio de una línea por fuera de un encabezado YAML o de un fragmento de código actúa como marcador de título.

2.1.1.3.2 Formato de texto

Mediante etiquetas, puede indicarse que cualquier texto sea formateado en itálica, negrilla o una combinación de ambas. También puede formatearse un texto como tachado.

*itálica*

**negrilla**

***negrilla e itálica***

~~tachado~~


En el documento de salida aparecerán asi:

itálica

negrilla

negrilla e itálica

tachado


Igualmente, usando etiquetas, puede indicarse el formato de subíndice o superíndice.

~subíndice~

^superíndice^


Así, cuando se escribe el siguiente texto en el documento fuente de Quarto,

Y = c~1~X + c~2~X^2^ + c~3~X^3^

aparece así en el documento final:

Y = c1X + c2X2 + c3X3

2.1.1.3.3 Comentarios dentro del texto

También es posible incluir comentarios en el texto, es decir, fragmentos de texto que se mostrarán únicamente en el documento fuente de Quarto, pero que no aparecerán en el documento final (Word, pdf, html…). Los símbolos <!-- marcan el inicio de un comentario. Para cerrarlo, se usan los símbolos -->.

<!-- Comentario que no aparecerá en el documento final -->


Los comentarios pueden útiles para incluir aclaraciones o recordatorios que deben tenerse presentes cuando se vuelva a revisar el documento fuente, pero que no tendrían sentido ni valor en el documento de salida.

También pueden resultar útiles para englobar grandes bloques (código y/o texto) que, de momento, no se desean enviar al documento de salida, pero que no se quieren borrar porque podrían usarse en posteriores renderizaciones.

2.1.1.3.4 \(\LaTeX\)

Como parte de lo que se ha denominado genéricamente texto (cualquier contenido que no forme parte de un encabezado YAML, de un fragmento de código o de alguna salida), Quarto también admite contenidos alimentados mediante código LaTeX, a través de los cuales es posible incluir ecuaciones, tablas y figuras.

Aunque la composición de textos en LaTeX es un tema vasto, no se requiere dominarla para escribir contenido básico. Quien no esté familiazado con este sistema de composición de textos puede aprender lo esencial en 30 minutos (… quizá un poco más), tal y como reza el título de uno de los tutoriales de Overleaf: Learn LaTeX in 30 minutes.

Si no tiene tiempo y/o paciencia para estudiar el tutorial de Overleaf, y lo único que necesita es una hoja de trucos (cheat sheet) que incluya los símbolos matemáticos más usuales, puede encontrarla aquí.

Los contenidos admitidos y la calidad en la que estos se presentan dependen del formato del documento de salida, siendo los documentos pdf los que mejor presentan las salidas basadas en LaTeX.

Salidas en pdf

Para generar archivos pdf es necesario tener instalado un procesador de LaTeX. Para la mayoría de usos basta con instalar TinyTeX, usando para ello el paquete tinytex:

tinytex::install_tinytex()

Si esto fuera insuficiente, habría que instalar una distribución completa de LaTeX, tal como MiKTeX. Este último es un software externo; no un paquete para R.

Existen dos modos de inclusión de ecuaciones usando código LaTeX:

  • Dentro de la línea (inline equation)

  • En línea aparte (display equation)

Para escribir una ecuación dentro de una línea, se rodea con símbolos dólar. El código LaTeX puede estar precedido y seguido de texto.

En el documento fuente de Quarto se escribiría así:

La varianza poblacional $\sigma^2$ se estima…

El texto final mostrará lo siguiente:

La varianza poblacional \(\sigma^2\) se estima…

Para escribir una ecuación en línea aparte (display equation) usando código LaTeX, se usa doble símbolo dólar al comienzo y al final.

En el documento fuente de Quarto se escribiría así:

$$
S^2=\frac{\sum\limits_{i=1}^{n}{\left(X_i-\overline{X}\right)^2}}{n-1}
$$

En el documento de salida aparecerá así:

\[ S^2=\frac{\sum\limits_{i=1}^{n}{\left(X_i-\overline{X}\right)^2}}{n-1} \tag{2.1}\]

Código \(\LaTeX\)

El código LaTeX es el indicado para presentar todo lo concerniente a ecuaciones. Las posibilidades de subíndice y superíndice que se ilustraron anteriormente usando marcación Markdown son bastante limitadas y no trascienden de esa tarea específica. Aun en tareas tan sencillas como ubicar una serie de subíndices y superíndices, LaTeX realiza una labor mucho más estética, adecuando el formato de toda la ecuación.

Para ilustrarlo, presentamos nuevamente la combinación lineal, usando código Markdown

Y = c~1~X + c~2~X^2^ + c~3~X^3^

En el documento de salida se obtiene lo siguiente:

Y = c1X + c2X2 + c3X3

Ahora presentamos la misma combinación lineal usando código LaTeX

$$
Y=c_1X+c_2X^2+c_3X^3
$$

En el documento de salida se obtiene lo siguiente:

\[ Y=c_1X+c_2X^2+c_3X^3 \]

¡La diferencia salta a la vista!

2.1.2 Creación de un nuevo documento Quarto

Existen varias formas de crear un nuevo documento de Quarto. Mediante el sistema de menús, se elige “File”, “New File”, “Quarto Document…”. Equivalentemente, puede usarse el ícono New File , seguido de la opción Quarto Document .

En cualquier caso, estos pasos llevan a una caja de diálogo, en la que se deja marcada la opción Document (que viene por defecto), y puede personalizarse la información contenida en los campos título y autor, así como el tipo de documento de salida.

El nuevo documento de Quarto contiene una serie elementos que pretenden servir de plantilla para el nuevo documento. Es posible eliminar todos los elementos y partir de un documento en blanco. Asimismo, podría mantenerse y editarse el encabezado YAML, acorde con los requerimientos del nuevo documento (cf. sección 2.1.1.1).

Seguidamente podrán ir estructurándose el documento con el texto y los fragmentos de código que sean del caso.

¡Personalice su plantilla!

Si usted llega a convertirse un un usuario frecuente de Quarto, puede resultarle conveniente tener una plantilla de un documento con un encabezado YAML que recoja sus preferencias.

Para iniciar un nuevo documento, no seguiría los pasos descritos anteriormente, sino que ubicaría una copia de la plantilla en su directorio de trabajo; la abriría desde allí y empezaría a escribir.

2.1.3 Estructura del documento Quarto

Aunque los desarrolladores de Quarto lo promocionan como una herramienta avanzada de edición de textos que puede usarse en cualquier ámbito, sin que tenga que estar relacionado ni con R ni con análisis estadísticos (novelas, libros de poesía, recetarios de cocina…), y esto es cierto, también es cierto que su mayor potencial se expresa cuando se usa para realizar, organizar y presentar análisis estadísticos. Suponiendo que este es el interés del lector, se presenta la estructura típica de un documento elaborado para tal fin.

La estrategia para la realización, organización y presentación de los análisis estadísticos usando Quarto difiere de la que se aplica cuando se llevan a cabo mediante un script tradicional de R o de algún otro lenguaje.

Lo que suele hacerse cuando se trabaja por la vía tradicional es ejecutar un gran script, cuyo código genera todos los resultados y al final se escribe el reporte usando algún editor de texto. Cuando se trabaja en Quarto, la idea es ir escribiendo el reporte en simultánea con la realización de los análisis y con la generación de los resultados: todo en un mismo documento.

En consonancia con lo anterior, no sería muy práctico tomar un script tradicional de R y vaciarlo dentro de un gran fragmento de código de Quarto, para escribir el reporte al final del documento.

Una estrategia mucho mejor, que da lugar a documentos mejor estructurados y, por tanto, más legibles, consiste en usar pequeños fragmentos de código con mucho texto intercalado, mediante el cual se anticipen y justifiquen los análisis que van a realizarse, y se discutan los resultados justo después de que estos se generen.

¡Fragmente el código!

Se recomienda dividir el código total en fragmentos tales que cada uno genere una única salida, de manera que sea posible discutirla justo después de que aparezca.

En el documento fuente de Quarto, tras el encabezado opcional YAML que iría al comienzo del documento (recuérdese que es optativo), pueden alternarse todos los fragmentos de código y texto que sean requeridos.

Un documento fuente de Quarto podría tener el siguiente aspecto:

---  
title: Ensayo primer semestre
---

La información de este análisis comprende las variables fisiológicas registradas entre abril y junio en aguacate Hass.

<!‑‑ La información parcial del segundo semestre, cuya cosecha no ha terminado aún, aparece en la segunda hoja del archivo “etapas.xlsx” ‑‑>

Inicialmente se cargan los paquetes que se usarán en el análisis y se importa y adecúa la base de datos.

```{r}
library(agricolae)
library(car)
data <- readxl::read_excel("etapas.xlsx")
data$etp <- factor(data$etp)
```

A continuación se analiza cada una de las respuestas con un modelo de análisis de varianza de una vía aleatorizado en DCA.

# Fotosíntesis

```{r}
anova <- aov(foto ~ etp, data)
shapiro.test(resid(anova))
```

    Shapiro-Wilk normality test

data:  resid(anova)
W = 0.98007, p-value = 0.001977

Puesto que los residuales del modelo exhiben desviaciones severas del supuesto de normalidad (p-value = 0.001977), se evalúan a continuación diferentes transformaciones.


A continuación se detallan los diferentes elementos de este documento Quarto.

La primera sección es el encabezado YAML, el cual, para el presente caso, contiene únicamente el título del documento (recuérdese que el encabezado YAML no es obligatorio).

A continuación aparece texto, mediante el cual se indican algunas características de los datos. Se intercala un comentario que no aparecerá en el documento de salida, pero que puede ser útil a futuro cuando se esté revisando nuevamente el documento fuente de Quarto. Le sigue más texto descriptivo mediante el cual se indica lo que hace el fragmento de código que aparece a continuación.

Seguidamente aparece un fragmento de código que realiza lo anunciado. Este fragmento de código no genera ninguna salida.

Le sigue una nueva sección de texto, que incluye una explicación de los análisis que se realizarán y un título para la primera variable, que a su vez sirve de marcador de navegación (cf. sección 2.1.1.3.1).

Aunque el fragmento en cuestión incluye varios procedimientos, estos generan un único resultado, el cual aparece justo después del fragmento y se comenta de inmediato usando una nueva sección de texto.

Este intercalamiento de código y texto es el que justifica el uso de código de manera fragmentada. Tal y como se ilustra en este ejemplo, el texto puede usarse para incluir títulos, que sirven como marcadores de navegación, o como texto ordinario, para anunciar algún análisis particular o para comentar los resultados obtenidos y quizá para justificar los análisis posteriores.

No hace falta ninguna instrucción particular para iniciar una sección de texto: basta con escribir; todo lo que esté por fuera de algún fragmento de código y del encabezado YAML se procesa como texto5.

2.1.4 Ejecución de los fragmentos de código

Cada uno de los fragmentos de código puede ejecutarse individualmente. De hecho, esta es la práctica recomendada cuando se está realizando un análisis. Esto permite ir construyendo el reporte a medida que los resultados van generándose e ir adaptando los análisis en función de los resultados previos.

Un fragmento de código puede ejecutarse en su totalidad o línea por línea. Al igual que en los scripts clásicos, la combinación de teclas permite ejecutar una instrucción o el conjunto de instrucciones seleccionadas (cf. R paso a paso: Ejecución de instrucciones). Mediante la combinación de teclas se ejecuta todo el fragmento de código, acción que igualmente puede realizarse presionando el triángulo verde que se ubica en la parte superior derecha de cada fragmento de código (Run Current Chunk).

Durante la construcción del documento Quarto, lo usual es ir ejecutando los fragmentos de código a medida que van escribiéndose. Y aunque las instrucciones en algunos fragmentos de código puedan depender de objetos creados en anteriores fragmentos, esto no representa ningún problema, puesto que todos los objetos creados permanecen disponibles en el ambiente de trabajo durante la sesión.

Debe tenerse presente, sin embargo, que toda nueva sesión de Quarto inicia con un ambiente de trabajo vacío, en el que no se habrá creado ningún objeto. Por tanto, cuando, partiendo de una nueva sesión de trabajo, se estuviera revisando algún fragmento de código particular, podría ser que este dependiera de fragmentos anteriores, en los que, por ejemplo, se hubieran importado o cargado los datos, definido nuevas variables, ajustado modelos, etc.

Para garantizar la correcta ejecución de un fragmento particular, podrían ubicarse y ejecutarse aquellos fragmentos previos de los cuáles dependa el fragmento de interés. Otra posibilidad —que en la mayoría de los casos puede ser más expedita— consiste en ejecutar el fragmento de interés junto con todos los fragmentos previos. Para ello se usa el ícono conformado por un triángulo gris sobre una barra horizontal verde, el cual está ubicado en la parte superior derecha de cada fragmento: (Run All Chunks Above).

Las salidas que se generen con la ejecución de un fragmento de código se muestran a continuación del correspondiente fragmento, bien sean salidas gráficas o de texto. Esto facilita la estructuración del informe final, mediante la incorporación de los comentarios que sean del caso, justo a continuación de las salidas.

2.1.5 Código en línea

También es posible combinar texto y código, mediante el denominado código en línea (inline code), el cual consiste en una expresión de código R inmersa dentro de un texto.

El código R en línea inicia con una comilla invertida y la letra r dentro de llaves (`{r}) y finaliza con una comilla invertida (`): `{r} print(x)`

El código en línea resulta útil para concatenar texto fijo con algún resultado variable, al estilo de las salidas generadas por la función cat (cf. R paso a paso: cat).

Considérese la siguiente adaptación de una parte del documento presentada anteriormente, en la que se guarda el resultado de la prueba Shapiro-Wilk en el objeto sw, para extraer posteriormente el valor p:

```{r}  
anova <- aov(foto ~ etp, data)  
sw <- shapiro.test(resid(anova))  
```

Puesto que no se satisface normalidad (p-value = `{r} sw[2]`)6, se evalúan diferentes transformaciones.

2.1.6 Código no ejecutable

En ocasiones se desea insertar código no ejecutable o estático dentro del texto, es decir, una cadena de caracteres que use la misma fuente del código y que tenga una apariencia especial, de manera que resalte dentro del texto normal, pero que no se ejecute.

Este recurso es útil para destacar nombres de funciones, paquetes u objetos, así como instrucciones cortas.

Para ello, se encierra entre comillas invertidas la cadena de caracteres que se quiera destacar. Así, por ejemplo, en el documento fuente de Quarto se escribiría lo siguiente:

La normalidad se evalúa con la instrucción `shapiro.test(resid(anova))`.

En el documento de salida se verá similar a lo siguiente:

La normalidad se evalúa con la instrucción shapiro.test(resid(anova)).

El formato particular que con el que se resalte el código estático dependerá del tipo de documento de salida.

La inserción de un bloque no ejecutable —que puede constar de una o más instrucciones— en línea(s) aparte, puede realizarse de varias formas:

  1. Introduciendo una indentación de 4 espacios antes de cada línea.

  2. Iniciando el bloque con una línea de tres comillas invertidas y finalizándolo con otra línea de tres comillas invertidas. En este caso no se agrega indentación a las líneas.

    ```
anova <- aov(foto ~ etp, data)
sw <- shapiro.test(resid(anova))
```

    En el documento renderizado aparecerá un bloque de aspecto similar al anterior, pero sin las comillas.

    El aspecto del bloque resultante es igual al que se obtiene indentando cada línea con 4 espacios. En el documento renderizado se usa la misma fuente que para el código, pero no se aplica ningún tipo de resaltado:

    anova <- aov(foto ~ etp, data)
    sw <- shapiro.test(resid(anova))

  1. Usando ```{.r} en la línea de apertura:

    ```{.r}
anova <- aov(foto ~ etp, data)
sw <- shapiro.test(resid(anova))
```

    Cuando se usa esta opción, el bloque resultante se formatea de la misma manera que el verdadero código ejecutable. No solo se usa la misma fuente que para el código, sino que se aplican los mismos resaltados, además de que todo el bloque aparece encerrado en una caja.

    anova <- aov(foto ~ etp, data)
sw <- shapiro.test(resid(anova))
¡Es seudocódigo!

Cualquiera de las anteriores opciones genera fragmentos de texto que —aunque tengan un aspecto similar o igual al del código— no son interpretados como código, por lo que no generan ninguna acción ni resultado.

Estas opciones son útiles en manuales y otros textos que tengan fines didácticos.

2.2 Documento de salida

Una vez depurado el documento fuente Quarto, se procede a generar el documento de salida, en cualquiera de los formatos html, pdf o Word.

Precaución 2.2: ¡Pero bien depurado!

Si hay errores, bien sea en la definición del encabezado YAML o en la ejecución de alguno de los códigos, el renderizado fallará.

Y cuidado, que el código erróneo —aun dentro de un comentario— sigue impidiendo el adecuado renderizado (cf. sección 3.17).

2.2.1 Renderizado

El paso entre el documento fuente de Quarto y el documento de salida exige una serie de proceso internos que en conjunto se denominan renderizado.

Durante el renderizado, se interpreta la sintaxis Markdown y se ejecutan todos los fragmentos de código incluidos en el archivo fuente de Quarto.

A partir de un archivo compilado intermedio, se genera el archivo final en el formato de salida especificado.

RStudio unifica todo el proceso descrito anteriormente. Para ello basta con presionar la combinación de teclas , o el ícono , con lo cual se generará un documento acorde con la opción indicada en el parámetro format del encabezado YAML (html por defecto).

¡Que todos los recursos estén disponibles!

Para evitar errores durante el proceso de renderizado, es necesario asegurar que estén disponibles todos los recursos que se invoquen, v. gr., bases de datos y funciones personalizadas.

Esta misma consideración debe tenerse presente cuando se comparta un documento Quarto con otro usuario, con la intención de que reproduzca y/o modifique los análisis: junto con el documento fuente de Quarto habrá que compartir los recursos que allí se invoquen.

¡Puede haber conflictos!

Cuando el proyecto se ubica en una carpeta sujeta a procesos de sincronización en la nube, tales como los de Dropbox, el renderizado no funciona adecuadamente. Para solucionar este problema, bien puede usarse otra ruta que no esté sujeta a sincronización o simplemente puede pausarse la sincronización mientras se esté realizando el renderizado.

2.2.2 Opciones de los fragmentos de código que determinan las salidas

Las opciones lógicas echo e include aplicadas a un fragmento de código permiten controlar los elementos que se visualicen u oculten en el documento de salida. La opción echo controla la visualización de los fragmentos de código, mientras que la opción include controla la visualización tanto del código como de los resultados generados. Por defecto, ambas opciones vienen preestablecidas con valor true, lo que significa que en el documento de salida se muestran tanto el código como los correspondientes resultados.

La visualización que se elija para el documento de salida dependerá de los objetivos y el estado del reporte. Si el objetivo del reporte es compartir el análisis con otros usuarios, mostrando no solo los resultados, sino también la manera en que se generaron, deberá incluirse el código (echo: true). Esto posibilita que todos los usuarios revisen los procedimientos con detalle e indiquen las modificaciones que sean del caso. Tales modificaciones se aplicarían, desde luego, sobre el documento fuente de Quarto.

En una etapa final, en la que se hayan depurado todos los procedimientos, podrá eliminarse la visualización del código (echo: false), manteniendo únicamente sus resultados y el texto.

Mediante la opción eval puede indicarse que no se evalúe un fragmento de código (eval: false), lo que resulta útil cuando se escriben tutoriales, en los que únicamente se desea mostrar el fragmento de código, sin que se ejecute ni se genere ninguna salida.

Es importante diferenciar el efecto que tienen las opciones include y eval:

  1. Mediante la opción include: false se instruye para que las salidas no incluyan ni el código ni los resultados que podría generar; sin embargo, el código sí se ejecuta. Esto es útil para realizar procedimientos internos (tales como como cargar un paquete o establecer parámetros gráficos) de los que no haya que dar cuenta en el documento final.

  2. Por su parte, eval: false muestra el código, pero este no se ejectua.

El valor por defecto para las tres opciones presentadas es true, lo que implica que todos los fragmentos de código se ejecutan y que tanto el fragmento de código como los resultados generados aparecen en el documento final. La siguiente tabla ilustra el efecto que tiene establecer el valor false para estas opciones.


Opción explícita Se ejecuta Se muestra el código Se muestran resultados
eval: false No Sí No
echo: false Sí No Sí
include: false Sí No No


Así, por ejemplo, para evitar que el primer fragmento de código que se presentó al ejemplificar la estructura de un documento de Quarto (cf. sección 2.1.3) apareciera en el documento de salida, realizando, sin embargo, su ejecución, se le agregaría la opción #| echo: false, así:

```{r}
#| echo: false

library(agricolae)
library(car)
data <- readxl::read_excel("etapas.xlsx")
data$etp <- factor(data$etp)
```
¡Si no funciona, no lo evalúe!

La opción eval: false es particularmente útil para evitar los problemas de renderización que surgen cuando se intenta evaluar código inadecuadamente depurado (cf. advertencia 2.2).

Equivalentemente, si el único objetivo es mostrar un fragmento de texto con apariencia de código, sin intención de realizar ningún tipo de depuración ni ejecución futura, puede usarse ```{.r} en lugar de ```{r} en la línea de apertura del fragmento (cf. sección 2.1.6).

2.2.3 Mensajes y advertencias

Los desarrolladores de código a menudo quieren mantener informado al usuario de lo que sucede tras bambalinas al cargar algunos paquetes o ejecutar algunas funciones.

Así, por ejemplo, es común que se informe cuando las funciones de algún paquete enmascaran funciones de los paquetes básicos (cf. R paso a paso: Paquetes)). Frecuentemente también se advierte sobre aspectos que deben tenerse en cuenta para interpretar adecuadamente los resultados.

Este tipo de información, aunque pueda ser útil mientras se ejecutan los procedimientos, suele evitarse en los documentos de salida; particularmente cuando se trata de un documento final. Para ello basta con especificar las siguientes opciones:

```{r}
#| warning: false
#| message: false
```
Directrices globales

Para hacer que estas opciones apliquen a todos los fragmentos de código, se establecen como directrices globales, incluyéndolas como subopciones7 de la clave execute en el encabezado YAML.

La especificación para que en el documento de salida únicamente aparezcan los resultados y el texto, sin código, mensajes ni advertencias, queda así:

---
execute:
  echo: false
  message: false
  warning: false
---

La lista completa de opciones, puede consultarse en el sitio de Quarto.

  1. Para el caso de los libros se requiere un archivo de Quarto por cada capítulo.↩︎

  2. Esto puede verificarse revisando la documentación de novedades de RStudio, donde se indica, por ejemplo, que la versión 2023.03.1 de RStudio incluye una actualización (upgrade) de Quarto a la versión 1.2.475↩︎

  3. En documentos más estructurados como los libros, establecen la jerarquía de los capítulos y de las secciones dentro de los capítulos.↩︎

  4. Para acceder al panel de navegación es necesario activar su visualización, bien sea marcando la correspondiente casilla en las opciones de vista o presionando la combinación de teclas Ctrl + b y eligiendo títulos.↩︎

  5. En su acepción más amplia: texto, tablas, ecuaciones…↩︎

  6. en el documento de salida aparecerá el correspondiente valor p.↩︎

  7. deben escribirse con una indentación de 2 espacios.↩︎