29  Formatos Quarto

29.1 Introducción

Hasta ahora, ha visto que Quarto se usa para producir documentos HTML. Este capítulo ofrece una breve descripción general de algunos de los muchos otros tipos de salida que puede producir con Quarto.

Hay dos formas de configurar la salida de un documento:

  1. De forma permanente, modificando el encabezado YAML:

    title: "Diamond sizes"
format: html

  2. De forma transitoria, llamando quarto::quarto_render() a mano:

    quarto::quarto_render("diamond-sizes.qmd", output_format = "docx")

    Esto es útil si desea producir múltiples tipos de salida mediante programación, ya que el argumento output_format también puede tomar una lista de valores.

    quarto::quarto_render("diamond-sizes.qmd", output_format = c("docx", "pdf"))

29.2 Opciones de salida

Quarto ofrece una amplia gama de formatos de salida. Puedes encontrar la lista completa en https://quarto.org/docs/output-formats/all-formats.html. Muchos formatos comparten algunas opciones de salida (p. ej., toc: true para incluir una tabla de contenido), pero otros tienen opciones que son específicas del formato (p. ej., code-fold: true colapsa fragmentos de código en un <details> etiqueta para la salida HTML para que el usuario pueda mostrarla a pedido, no es aplicable en un documento PDF o Word).

Para anular las opciones predeterminadas, debe usar un campo format expandido. Por ejemplo, si quisiera representar un html con una tabla de contenido flotante, usaría:

format:
  html:
    toc: true
    toc_float: true

Incluso puede renderizar en múltiples salidas proporcionando una lista de formatos:

format:
  html:
    toc: true
    toc_float: true
  pdf: default
  docx: default

Tenga en cuenta la sintaxis especial (pdf: default) si no desea anular ninguna opción predeterminada.

Para representar todos los formatos especificados en el YAML de un documento, puede usar output_format = "all".

quarto::quarto_render("diamond-sizes.qmd", output_format = "all")

29.3 Documentos

El capítulo anterior se centró en la salida html predeterminada. Hay varias variaciones básicas sobre ese tema, generando diferentes tipos de documentos. Por ejemplo:

  • pdf crea un PDF con LaTeX (un sistema de diseño de documentos de código abierto), que deberá instalar. RStudio le preguntará si aún no lo tiene.

  • docx para documentos de Microsoft Word (.docx).

  • odt para documentos OpenDocument Text (.odt).

  • rtf para documentos en formato de texto enriquecido (.rtf).

  • gfm para un documento Markdown de GitHub (.md).

  • ipynb para Jupyter Notebooks (.ipynb).

Recuerde, al generar un documento para compartir con los responsables de la toma de decisiones, puede desactivar la visualización predeterminada del código configurando las opciones globales en el documento YAML:

execute:
  echo: false

Para los documentos html, otra opción es hacer que los fragmentos de código estén ocultos de forma predeterminada, pero visibles con un clic:

format:
  html:
    code: true

29.4 Presentaciones

También puede usar Quarto para producir presentaciones. Obtiene menos control visual que con una herramienta como Keynote o PowerPoint, pero insertar automáticamente los resultados de su código R en una presentación puede ahorrar una gran cantidad de tiempo. Las presentaciones funcionan dividiendo su contenido en diapositivas, con una nueva diapositiva que comienza en cada segundo encabezado de nivel (##). Además, los encabezados de primer nivel (#) indican el comienzo de una nueva sección con una diapositiva de título de sección que, de manera predeterminada, está centrada en el medio.

Quarto admite una variedad de formatos de presentación, que incluyen:

  1. revealjs - Presentación HTML con revealjs

  2. pptx - Presentación de PowerPoint

  3. beamer - Presentación en PDF con LaTeX Beamer.

Puede leer más sobre la creación de presentaciones con Quarto en https://quarto.org/docs/presentations.

29.5 Interactividad

Al igual que cualquier documento HTML, los documentos HTML creados con Quarto también pueden contener componentes interactivos. Aquí presentamos dos opciones para incluir interactividad en sus documentos Quarto: htmlwidgets y Shiny.

29.5.1 htmlwidgets

HTML es un formato interactivo y puede aprovechar esa interactividad con htmlwidgets, funciones de R que producen visualizaciones HTML interactivas. Por ejemplo, tome el mapa del leaflet a continuación. Si está viendo esta página en la web, puede arrastrar el mapa, acercar y alejar, etc. Obviamente, no puede hacer eso en un libro, por lo que Quarto inserta automáticamente una captura de pantalla estática para usted.

library(leaflet)
leaflet() |>
  setView(174.764, -36.877, zoom = 16) |> 
  addTiles() |>
  addMarkers(174.764, -36.877, popup = "Maungawhau")

Lo mejor de los htmlwidgets es que no necesita saber nada sobre HTML o JavaScript para usarlos. Todos los detalles están envueltos dentro del paquete, por lo que no necesita preocuparse por eso.

Hay muchos paquetes que proporcionan htmlwidgets, incluidos:

  • dygraphs para visualizaciones interactivas de series de tiempo.

  • DT para tablas interactivas.

  • threejs para gráficos 3d interactivos.

  • DiagrammeR para diagramas (como diagramas de flujo y diagramas de enlace de nodo simples).

Para obtener más información sobre los htmlwidgets y ver una lista completa de los paquetes que los proporcionan, visite https://www.htmlwidgets.org.

29.5.2 Shiny

htmlwidgets proporcionar interactividad del lado del cliente — toda la interactividad ocurre en el navegador, independientemente de R. Por un lado, eso es genial porque puedes distribuir el archivo HTML sin ninguna conexión con R. Sin embargo, eso limita fundamentalmente lo que puede hacer con las cosas que se han implementado en HTML y JavaScript. Un enfoque alternativo es usar shiny, un paquete que le permite crear interactividad usando código R, no JavaScript.

Para llamar al código Shiny desde un documento Quarto, agregue server: shiny al encabezado YAML:

title: "Shiny Web App"
format: html
server: shiny

Luego puede usar las funciones de entrada “input” para agregar componentes interactivos al documento:

library(shiny)

textInput("name", "What is your name?")
numericInput("age", "How old are you?", NA, min = 0, max = 150)

Y también necesita un fragmento de código con la opción de fragmento context: server que contiene el código que debe ejecutarse en un servidor Shiny.

Dos cuadros de entrada uno encima del otro. Uno de arriba dice: "What is your name?", el de abajo, "How old are you?".

Luego puede hacer referencia a los valores con input$name y input$age, y el código que los usa se volverá a ejecutar automáticamente cada vez que cambien.

No podemos mostrarle una aplicación brillante en vivo aquí porque las interacciones brillantes ocurren en el lado del servidor. Esto significa que puede escribir aplicaciones interactivas sin saber JavaScript, pero necesita un servidor para ejecutarlas. Esto introduce un problema logístico: las aplicaciones Shiny necesitan un servidor Shiny para ejecutarse en línea. Cuando ejecuta aplicaciones Shiny en su propia computadora, Shiny configura automáticamente un servidor Shiny para usted, pero necesita un servidor Shiny público si desea publicar este tipo de interactividad en línea. Esa es la compensación fundamental de shiny: puede hacer cualquier cosa en un documento brillante que pueda hacer en R, pero requiere que alguien esté ejecutando R.

Para aprender más sobre Shiny, recomendamos leer Mastering Shiny de Hadley Wickham, https://mastering-shiny.org.

29.6 Sitios web y libros

Con un poco de infraestructura adicional, puede usar Quarto para generar un sitio web completo o un libro:

  • Coloque sus archivos .qmd en un solo directorio. index.qmd se convertirá en la página de inicio.

  • Agregue un archivo YAML llamado _quarto.yml que proporciona la navegación para el sitio. En este archivo, establezca el tipo de project en book o website, por ejemplo:

    project:
  type: book

Por ejemplo, el siguiente archivo _quarto.yml crea un sitio web a partir de tres archivos fuente: index.qmd (la página de inicio), viridis-colors.qmd y terrain-colors.qmd.

project:
  type: website

website:
  title: "A website on color scales"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: viridis-colors.qmd
        text: Viridis colors
      - href: terrain-colors.qmd
        text: Terrain colors

El archivo _quarto.yml que necesita para un libro tiene una estructura muy similar. El siguiente ejemplo muestra cómo puede crear un libro con cuatro capítulos que se muestra en tres salidas diferentes (html, pdf y epub). Una vez más, los archivos de origen son archivos .qmd.

project:
  type: book

book:
  title: "A book on color scales"
  author: "Jane Coloriste"
  chapters:
    - index.qmd
    - intro.qmd
    - viridis-colors.qmd
    - terrain-colors.qmd

format:
  html:
    theme: cosmo
  pdf: default
  epub: default

Le recomendamos que utilice un proyecto de RStudio para sus sitios web y libros. Basado en el archivo _quarto.yml, RStudio reconocerá el tipo de proyecto en el que está trabajando y agregará una pestaña Build al IDE que puede usar para renderizar y obtener una vista previa de sus sitios web y libros. Tanto los sitios web como los libros también se pueden renderizar usando quarto::quarto_render().

Lea más sobre sitios web de Quarto en https://quarto.org/docs/websites y sobre libros en https://quarto.org/docs/books.

29.7 Otros formatos

Quarto ofrece aún más formatos de salida:

Vea https://quarto.org/docs/output-formats/all-formats.html para una lista de incluso más formatos.

29.8 Resumen

En este capítulo le presentamos una variedad de opciones para comunicar sus resultados con Quarto, desde documentos estáticos e interactivos hasta presentaciones, sitios web y libros.

Para aprender más sobre la comunicación efectiva en estos diferentes formatos, recomendamos los siguientes recursos: