Reportes Quarto en R: clase 1

Fecha de publicación

4 de enero de 2025

Quarto es una herramienta que te permite generar documentos y reportes de manera muy sencilla utilizando bloques de código de R. En estos reportes puedes incluir tablas, gráficos, y mucho más, de forma atractiva, para poder compartir tus análisis y resultados con otras personas.

Crear un reporte Quarto

En RStudio, crear un nuevo archivo desde New File, y elegir Quarto Document.

Cuando hagamos los cambios que deseemos, presionamos el botón Render para generar el reporte a partir del código. El reporte se abre en el visor Viewer, y queda guardado como un archivo .html para abrirlo con un navegador web.

Markdown

Markdown es el formato de escritura usado en Quarto. Permite escribir texto enriquecido a aprtir de texto plano (código), usando síbolos de marcado para definir el estilo del texto. Más información en esta guía

Algunos de los estilso básicos que puedes darle al texto:

**negrita**
*itálica* o _itálica_
<u>subrayado</u>
~~tachado~~
`código`

Resultarían en lo siguiente:

negrita

itálica o itálica

subrayado

~~tachado~~

código

Otras posibilidades

Puedes insertar separadores escribiendo cuatro guiones. Estos resultan en una línea vertical, como la de encima del subtítulo anterior.

----

Para agregar un enlace en markdown, escirbimos el texto del enlace entre corchetes, y luego el enlace enter paréntesis:

[Texto](http://enlace.cl)

El enlace se vería así.

Para agregar una nota al pie se escribe el número de la nota entre corchetes, antecedido por el símbolo de superíndice o potencia ^.

Ejemplo de una nota al pie¹. También se puede agregar directamente en el texto².

Agregar una nota al pie[^1].
[^1]: Esta es una nota al pie

También se puede agregar directamente en el texto^[De esta forma].

Configuración básica

Los documentos Quarto se configuran principalmente desde su encabezado o header. Éste es el código que se encuentra en las primeras líneas, escrito entre tres guiones (---). Este código está escrito en yaml, y permite configurar casi todos los aspectos de apariencia del documento.

Títulos

Puedes cambiar el título del documento en la etiqueta title.

---
title: "Probando"
lang: es
---

También puedes agregar autoría y fecha, simplemente agregando las configuraciones debajo de las existentes:

---
author: "Bastián Olea Herrera"
date: 2025-04-01
lang: es
---

Puedes cambiar el texto que aparece arriba de alguna de las etiquetas. Sugiero buscar en internet este tipo de cosas, ya que Quarto tiene muy buena documentación.

lang: es
language: 
  title-block-author-single: "Creado por"

Puedes personalizar el titular del documento con estas etiquetas:

title-block-banner: "#f0f3f5"
title-block-banner-color: "black"

Para más información sobre el bloque titular, revisar esta guía.

Índices o tablas de contenido

A medida que agregas títulos markdown, puedes agregar una tabla de contenidos que se actualizará automáticamente con los títulos que vayas agregando. Para más información, revisa esta otra guía.

Activa la tabla de contenidos reemplazando el format de tu documento por uno personalizable:

format:
  html
    toc: true

Personaliza el nivel de titulares que aparecen en la tabla de contenidos con toc-depth, y puedes hacer que las secciones se numeren automáticamente con number-sections.

format:
  html
    toc: true
    number-sections: true
    toc-expand: 2

También poner enlaces debajo del índice, por ejemplo a tu sitio web o redes sociales. Los enlaces pueden tener un ícono personalizado.

format:
  html:
    other-links:
      - text: Enlace 1
        href: https://data.nasa.gov/
      - text: Enlace 2
        icon: file-code
        href: https://data.nasa.gov/

Temas

Configura el tema de tu reporte para cambiar su apariencia completa, incluyendo colores, espaciados, tipografías y más. Revisa la lista de temas en este enlace.

Tan solo agregando theme y el nombre del tema (de la lista de temas) cambiarás la apariencia completa de tu reporte.

theme: darkly

Personaliza la tipografía y el tamaño global de las letras:

mainfont: Courier
fontsize: "20px"

Autocontenido

Los reportes Quarto son archivos web, y como tales requieren de dependencias externas, como scripts, estilos e imágenes, que se guardan como archivos. Éstos se guardan en una carpeta con el mismo nombre de tu reporte. Pero esto puede resultar inconveniente para compartir los documentos, además de generar desorden. Para que el documento no tenga dependencias externas, sino que sea portable y auto-contenido en un sólo archivo .html, podemos hacer que el reporte contenga todas sus dependencias dentro de sí agregando lo siguiente al format de nuestro documento:

format:
  html:
    embed-resources: true

Recomiendo siempre usar esta opción, a pesar de que puede generar archivos más pesados.

Disposición

Veamos algunas formas de personalizar la disposición de los reportes, como columnas, pestañas y contenido en los márgenes. Para más información, consulta esta guía oficial

Columnas

Para escribir contenido en columnas, debes crear un bloque (::::) con el estilo .columns, y dentro de él, crear dos secciones con el estilo .column indicando el porcentaje del ancho que tomarán:

:::: {.columns}

::: {.column width="40%"} 
Columna izquierda
:::

::: {.column width="60%"}
Columna derecha
:::

::::

Si quieres agregar un espacio entre ambas columnas, crea una columna vacía que sea más delgada:

:::: {.columns}

::: {.column width="40%"} 
Columna izquierda
:::

::: {.column width="5%"} 
:::

::: {.column width="55%"}
Columna derecha
:::

::::

Ejemplo:

Columna izquierda

Texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto.

Columna derecha

Texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto.

Otra forma de hacer lo mismo es usar BootStrap (como en Shiny), usando un sistema de columnas que divide el ancho de la página en 12 partes:

:::: {.grid}

::: {.g-col-3}
Primera columna
:::
  
::: {.g-col-9}
Segunda columna
:::
  
::::

Pestañas

Para poner contenido dentro de pestañas, crea un bloque con el estilo .panel-tabset, y dentro de éste, todos los títulos markdown que pongas (##, ###, etc.) aparecerán en su propia pestaña:

::: {.panel-tabset}

## Pestaña 1
Contenido de la pestaña 1

## Pestaña 3
Contenido de la pestaña 2

## Pestaña 3
Contenido de la pestaña 3
:::

Si usas como estilo {.panel-tabset .nav-pills}, los botones de las pestañas aparecerán rellenados.

Ejemplo:

Contenido de la pestaña 1

Texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto.

Contenido de la pestaña 2

Contenido de la pestaña 3

Texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto.

Contenido al margen

Puedes agregar cualquier contenido en los márgenes del documento, como fórmulas, aclaraciones, o incluso tablas y gráficos, usando un bloque con el estilo .aside:

::: {.aside}
\
Esto es un ejemplo. Esto es un ejemplo. Esto es un ejemplo. Esto es un ejemplo. Esto es un ejemplo. Esto es un ejemplo. Esto es un ejemplo. Esto es un ejemplo. Esto es un ejemplo. 
:::

Ejemplo: Este texto es muy complicado y requiere información! Texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto texto.

Información extra al margen del reporte!

Código

La gracia de Quarto es combinar código con texto. Para agregar código, creamos bloques o chunks, en los que podemos escribir código de R, y sus resultados aparecerán en el documento.

library(ggplot2)

iris |> 
  ggplot() +
  aes(x = Sepal.Length, y = Sepal.Width) +
  geom_point(color = "purple4", alpha = 0.4, size = 4) +
  theme_minimal()

Si queremos que no aparezca el código, y sólo aparezca el output, agregamos #| echo: false al inicio del bloque. Para omitir que los bloques impriman mensajes y/o alertas, agregamos #| message: false y #| warning: false respectivamente.

Para configurar el tamaño de los gráficos, agregamos al bloque las opciones #| fig-width: 4 o #| fig-height: 6 para modificar el ancho o alto, respectivamente. Por defecto, los gráficos son de 7 x 5.

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

iris |> 
  ggplot() +
  aes(x = Sepal.Length, y = Sepal.Width) +
  geom_point(color = "orange", alpha = 0.4, size = 4) +
  theme_minimal()
```

Código entre el texto

Para integrar código en el texto de los párrafos de tu reporte, por ejemplo, para insertar una cifra, escribimos comillas invertidas (), la letrar`, y el código cuyo output queremos que aparezca en el documento:

`r iris$Species[1]`

`r length(iris)`

`r mean(iris$Sepal.Length)`

De esta forma podemos agregar texto que proviene desde nuestros datos: el dataset iris tiene 5 variables que describen 3 especies de plantas.

Reportes parametrizados

Los reportes parametrizados nos permiten cambiar aspectos del código del documento al cambiar una variable definida en el encabezado del mismo.

Si tengo un reporte donde los resultados dependen de un filtro en mis datos, definimos el valor de la variable a filtrar en el encabezado bajo la etiqueta params:

(Este ejemplo se encuentra en el repositorio del curso, carpeta quarto_reportes, archivo iris_params.qmd)

params:
  especie: "virginica"

Luego, en el código del documento, puedo acceder al contenido de especie usando params$especie. Entonces puedo cambiar el valor de especie desde el encabezado del reporte.

La idea de poder hacer esto es diseñar el reporte para producir resultados en base a la variable parametrizada, para que podamos obtener múltiples reportes solamente cambiando la variable parametrizada. De este modo, podemos obtener el reporte desde un script distinto con la función quarto_render() del paquete {quarto}:

library(quarto)
quarto_render(
  input = "iris_params.qmd",
  execute_params = list(
    especie = "setosa"
  )
)

Así solamente se necesita cambiar especie para obtener un reporte en .html listo para presentar.

El potencial de esto es poder generar x cantidad de reportes por medio de una iteración o loop que pase por todos los valores de la variable que parametrizamos:

walk(c("virginica", "setosa", "versicolor"), ~{
  quarto_render(
    input = "iris_params.qmd",
    output_file = paste0("iris_params_", .x, ".html"),
    execute_params = list(
      especie = .x
    )
  )
})

Hay que asegurarse de que los nombres de los reportes generados sean distintos, cambiándolos en output_file = paste0("iris_params_", .x, ".html") para que tengan en su nombre el valor del parámetro usado.

También hay que preocuparse de que los reportes sean autocontenidos conteniendo embed-resources: true en el encabezado.

De esta forma obtenemos tres reportes con el trabajo de haber diseñado sólo uno. Pero si nuestra variable de parametrización tiene 10 o 100 valores, habremos obtenido 10 o 100 reportes gratis!

Notas

Nota al pie.↩︎
De esta forma↩︎