Tema 04 - Introducción a Quarto

Pedro Albarrán

Dpto. de Fundamentos del Análisis Económico. Universidad de Alicante

Alberto Pérez

El sistema de publicaciones Quarto

  • Orientado al análisis de datos reproducible: combina código, resultados y comentarios

  • Útil como cuaderno de trabajo del código y para comunicar resultados en un documento final para tomar decisiones

  • Instalar Quarto para vuestro sistema operativo desde aquí

  • La guía y referencia completa de Quarto están en su Web

  • Un documento de Quarto se renderiza, procesando cada componente (código, resultado de ejecutarlo y texto) para producir documentos en varios formatos: html, PDF, Word, presentaciones, etc.

Documentos de Quarto: Crear y Guardar

  • Creamos un proyecto de Quarto en File > New Project > New Directory > Quarto Project o en el icono de proyectos

    • Ignoramos el documento que se crea por defecto

  • Creamos un nuevo documento a partir de una plantilla en RStudio con o File > New File > Quarto Document

    • Podemos elegir Título, Autor/a y formato de salida (HTML, por defecto)

  • Se guarda con o con File > Save, con extensión .qmd

  • Se renderiza con Render al formato de salida elegido

  • En el botón de engranaje Engranaje se pueden cambiar algunas opciones

    • p.e., dónde se visualiza la salida (en ventana aparte o en RStudio)

Documentos de Quarto: formato de salida

  • El renderizado crea un archivo en el mismo directorio donde está el archivo de Quarto .qmd

  • En el caso de HTML, se crea tanto un archivo con extensión .html como un subdirectorio del mismo nombre con componentes necesarios (ej., imágenes, css)

    • solo podemos visualizar correctamente el archivo .html en cualquier navegador si copiamos a otro lugar tanto el .html como el subdirectorio

  • Para crear PDFs, se necesita una distribución de LaTeX: instala una escribiendo en la pestaña de “Terminal” (a la derecha de la consola):

quarto install tool tinytex

Documentos de Quarto: Texto con Markdown

  • Los componentes de texto están escritos en Markdown: un conjunto ligero de convenciones para archivos de texto sin formato. Por ejemplo,

    • todo lo escrito entre dos * como **Hola** se renderiza en negritas

    • se utiliza # para indicar encabezados de secciones

  • En el menú de ayuda tenemos una descripción completa (Markdown quick reference) y “chuletas” (Cheatsheets)

  • También son útiles la web de Quarto y este libro online.

  • RStudio incorpora un editor visual de documentos de Quarto, similar a un procesador de texto

Editor Visual de Quarto en RStudio

  • En documentos .qmd, se puede elegir entre editar la fuente (source) de Markdown, como texto sencillo, o editar el documento de forma Visual en

  • En el modo visual, en esa misma barra de herramientas se tienen accesos a

    • formatos de texto (negritas, cursivas, encabezamientos) y listas
    • insertar enlaces, imágenes, notas a pie de página, tablas
    • incluir ecuaciones (en LaTeX)
    • también insertar directamente código HTML, comentarios, etc.

  • Se puede configurar la corrección ortográfica en Tools > Global Options > Spelling: agregar/seleccionar el diccionario de Español

Formato en la cabecera: el bloque YAML

  • Al principio del documento, entre dos líneas con ---, se pueden especificar varias opciones del documento: título, autor, fecha, formato de salida

  • Los formatos de salida son html, pdf, docx (y otros en Quarto Presentations)

  • También se especifican opciones globales del documento, algunas específicas de cada tipo de salida (ver la referencia para html y otros formatos)

      ---
  title: "Título"
  author: Autor 
  date: 15-octubre-2023
  format:
    html:
      toc: true              # índice
      number-sections: true  # secciones numeradas
      embed-resources: true  # archivo html autocontenido
      theme: united          # más temas: https://bootswatch.com/3/
  ---

Fragmentos o celdas de código

  • Insertamos código en medio del texto con el icono (visual)

    • Si pulsamos , escribimos r y luego un código, el documento de salida incluirá el resultado de ejecutar el código

  • Podemos incluir un fragmento de código (de varias líneas), con , en el desplegable o Ctrl + Alt + I

    • Se puede personalizar cómo se muestran varios aspectos del código y de sus resultados

    • bien para una celda concreta de código, incluyendo opciones de celda

    • o para todo el documento en la cabecera: las opciones de html están en la sección de código de su referencia (y similar para otros formatos)

Opciones para una celda de código

  • Las opciones se incluyen al principio de una celda precedidas por #|

  • echo: true muestra el código en la salida (o no con echo: false)

  • eval: true ejecuta el código (o no con eval: false)

    • Si un fragmento no se evalúa, sus resultados no se muestran y ni están para otras celdas posteriores (p.e., cargar datos o una biblioteca para usar luego)

  • output: true incluye los resultados del código

  • include: false no incluye ni el código ni su resultado, pero se evalúa

  • Se muestran (o no) los mensajes, errores y avisos de ejecutar un código con las opciones message, error y warning, respectivamente.

  • label: etiqueta para identificar la celda

Opciones para una celda de código (cont.)

  • code-fold: true oculta el código pero da opción a mostrarlo

  • Cómo mostrar resultados de texto y numéricos:

    • results: hide (no mostrar)
    • results: hold (mostrar todo, no el resultado de cada línea)

  • fig-cap y tbl-cap para los títulos de las figuras y tablas

  • Cómo mostrar los gráficos: fig-show

    • hide y hold son como en results
    • asis muestra el gráfico como se generó
    • animate concatena varios gráficos en una animación

  • fig-width y fig-height: dimensiones (reales, en pulgadas) de una figura

  • out-width y out-height: ídem en el documento de salida (% de las reales)

Opciones para una celda de código (y 3)

  • fig-align: mostrar la figura centrada o alineada a derecha o izquierda

  • layout-ncol: en cuantas columnas se componen los resultados

```{r}
#| layout-ncol: 2
#| fig-show: hold
ggplot(data = cars) + geom_histogram(aes(x = speed))  # izquierda
ggplot(data = cars) + geom_histogram(aes(x = dist))   # derecha
```

Opciones globales para todas las celdas

  • En la cabecera, especificamos opciones por defecto para las celdas de código

    • p.e., de ejecución como echo, eval, etc. en execute (ver aquí y aquí)

      ---
execute:
  echo: false
  warning: false
---
    ---
    format:
      html:
        code-fold: true
        cap-location: bottom
        fig-align: center
        df-print: paged      # cómo visualizar tablas
    ---

Ejecución de código en un documento .qmd

  • Renderizar un .qmd crea un espacio de trabajo para ejecutar el código distinto del que vemos en RStudio (diferentes objetos, bibliotecas, etc.)

    • si no estamos en un proyecto, el directorio de trabajo puede diferente

  • Comprobamos los resultados del código del .qmd ejecutándolo sin renderizar: línea a línea, la celda completa con o todas las anteriores con

    • así, el código pasa a la consola y sí forma parte del espacio de la sesión actual

    • nos aseguramos de que no hay errores (ej., objetos previos no definidos)

  • Para garantizar que la sesión actual incluye sólo resultados de las celdas del .qmd, incluimos una celda inicial con include: false con

    • rm(list = ls()): al ejecutar todas las celdas previas, empezamos con una sesión sin objetos previos

    • Todas las bibliotecas (ej., tidyverse) que utilizaremos en varias celdas

Mejorar la salida de tablas

  • Los resultados de muchas funciones de R no son visualmente “profesionales” en el documento de salida de .qmd

  • Varias bibliotecas cambian algunas salidas por defecto (printr) u ofrecen funciones para mejorarlas (pander, xtable)

  • Un enfoque “fácil”:

    1. crear un data frame con los resultados que queremos mostrar en la tabla

    2. usar la función kable() de la biblioteca knitr para mostrarlo

  • La biblioteca kableExtra ofrece más opciones.

  • broom::tidy() (de tidyverse) convierte mucho objetos de R (como listas con resultados de comandos) en tibbles

  • Otras bibliotecas similares: modelsummary (convierte listas en tablas)

Comentarios finales

  • Dashboards (tableros): son presentaciones visuales e interactivas de los resultados claves de un análisis que permiten una comunicación más efectiva

  • Jupyter Notebook: son otra forma de combinar texto, código y resultados en un documento. Desarrollados para Python, admiten varios lenguajes de programación (como Quarto)

    • se crean, visualizan y ejecutan en navegadores web, pero son fácilmente modificables, localmente u online en JupyterLab o con Google Colab

    • Quarto renderiza libros de Jupyter, creados en .qmd o en su propio formato

  • Muchas herramientas están preparadas para Python y R porque se usan a menudo indistintamente o combinados