Hola, ¡Quarto!

productivo • reproducible • colaborativo • interactivo

Paula Pereda Suárez
R-Ladies MVD

paula.quarto.pub/hola-quarto

ilustraciones por allison horst

Thank you so much, we’re excited to be here! Mine and I have been using Quarto for the last year; she has been teaching and contributing to the development of Quarto it since its earliest days and Openscapes has been the first external users of Quarto. As we’ve woven it into our work we realize we love it, and we’re thrilled to welcome you to Quarto.

Hola, ¿Quarto?

But also, we know you have questions. We did too. What is Quarto? Why is Quarto? And how does it relate to R Markdown and the workflows you already have?

–> Well

Quarto unifica y extiende
el ecosistema de R Markdown

Quarto unifies & extends the R Markdown ecosystem.

Quarto unifica y extiende
el ecosistema de R Markdown

lo unifica para personas que aman R Markdown

lo extiende para gente que no conoce R Markdown

It unifies it for people who love R Markdown by reducing little points of friction, so that websites, books, and slides all have a common approach.

And it extends it for people who don’t know RMarkdown by being a friendly way to work reproducibly and publish documents that have text and code in the same place

Quarto es un nuevo, open-source,
científico y técnico
sistema de publicación

Quarto is a new open-source scientific and technical publishing system.

Quarto es un nuevo, open-source,
científico y técnico
sistema de publicación

el objetivo es hacer el proceso de crear
y colaborar sensiblemente mejor

The goal is to make the process of creating and collaborating dramatically better.

–> Maneja entradas en múltiples idiomas, y salidas en múltiples formatos, todo pasando por la misma maquinaria.

–> Hoy, les voy a presentar Quarto contando cómo funciona y una demostración.

El ecosistema de R Markdown

Julie mentioned unifying the R Markdown ecosystem so let’s dig a bit more into what that means…

Think of all the packages from the R Markdown universe that you’ve come to love and rely on over the years. Each package addresses a different need and offers a different output: for example, you can use blogdown or distill for creating websites and blogs, bookdown for writing a book, rticles for writing journal articles, etc.

Quarto: La nueva generación de R Markdown

Quarto unifica la funcionalidad de estos paquetes,

basándose en Pandoc en el aspecto técnico

y en el lado humano: más de una década de experiencia desarrollando, manteniendo y ajustando estos paquetes, así como los comentarios de la comunidad sobre los paquetes de extensión R Markdown.

Tal esfuerzo de unificación presenta una fantástica oportunidad para identificar y abordar las lagunas de funcionalidad y las ineficiencias en la experiencia del usuario, y el proceso de construcción de Quarto no ha sido diferente.

Highlights de Quarto

Implementación coherente de funciones atractivas y prácticas en todos los productos: tabsets, plegado de código, resaltado de sintaxis, etc.

Valores por defecto más accesibles y mejor soporte para la accesibilidad.

Guías, especialmente útiles para los principiantes: Completado de YAML, errores de sintaxis informativos, etc.

Soporte para otros lenguajes como Python, Julia, Observable, y más a través del motor Jupyter para pedazos de código ejecutables.

Algunas de estas mejoras son

–> Implementación consistente de características atractivas y prácticas en todos los resultados, como tabsets, plegado de código y resaltado de sintaxis,

–> valores por defecto más accesibles, así como un mejor soporte para la creación de documentos accesibles,

–> Guías que son particularmente útiles para los nuevos alumnos, como la finalización de YAML y errores de sintaxis informativos,

–> y quizás lo más emocionante para aquellos que no vienen del ecosistema R, Quarto ofrece soporte para otros lenguajes como Python, Julia, Observable, y más a través del motor Jupyter para trozos de código ejecutables. Y está diseñado para ser expandible a más motores y lenguajes, incluso aquellos que podrían no existir hoy en día.

[pause] Así que por ahora estoy asumiendo que muchos de ustedes ya han comenzado a jugar con Quarto, o están esperando que yo lo haga. Así que, ¡vamos a sumergirnos y ver de qué se trata todo el alboroto de Quarto!

• Open hello.Rmd with source editor -> knit
• Change to visual editor -> knit
• Close file -> change file type to .qmd -> open + render
• Change output: html_document to format: html -> render
• Click on Render on save
• Change to format: pdf -> render -> then change back
• Add chunk option echo: false to the first chunk
• Add execute > echo: false to the yaml
• Add alt text to figure in second code chunk -> save to render
• Change to format: revealjs -> save to render
• Add H2 to break slides
• Change to format: html
• Add index.qmd with File > New Quarto Document
• Add _quarto.yml for website
• Relaunch project
• Show new Build tab
• Render site, show _site folder
• Add freeze to _quarto.yml
• From terminal: quarto publish

¿Cómo funciona?

Now that you’ve all had a chance to see Quarto in action, you might be wondering, “how are R Markdown and Quarto different”?

The main difference is that with R Markdown, the R package rmarkdown does the heavy lifting of going from the source Rmd file to the the output, using knitr for evaluating the code chunks.

–> With Quarto, on the other hand, the Quarto command line interface, or the Quarto CLI, does the orchestration of processing executable code chunks with either knitr or jupyter and then converting the resulting markdown file to the desired output.

While this is technically impressive, I’ll be honest, it’s not exactly what sparked my interest in Quarto in the first place.

Quarto facilita la transición entre formatos

Documento

lesson-1.qmd

title: "Lesson 1"
format: html

Presentación

lesson-1.qmd

title: "Lesson 1"
format: revealjs

Sitio Web

_quarto.yml

project:
  type: website

website: 
  navbar: 
    left:
      - lesson-1.qmd

What did spark my interest was how how straightforward it is with Quarto to move between output formats.

As an educator, two things are of utmost importance to me about the tools I use to create my materials: reproducibility and ease of transition between output formats, like documents to slides to websites to books.

Over the last year of using Quarto for pretty much everything, I’ve felt like I’ve finally found the tool that lets me go from one output type to the other with minimal, if any, futzing around with my source code beyond the yaml. For example, here are common things I produce

–> a lesson in document form
–> the same content in presentation form
–> the same content on a page in a website,

and you can see that all that needed to change going between these formats is a few lines in the yaml. Nothing in the content part of my document. No slide breaks to remove, no citation style to change, no headings to re-level. This ease of transition has freed up time to focus my time on content, and that, folks, is the dream!

Quarto facilita el intercambio abierto

Las herramientas que facilitan compartir lo que hacés con el mundo (?) en la web es increíblemente útil.

No sólo es útil para uno, sino para todo el mundo ya que facilita el intercambio abierto de conocimientos para aprender y reutilizar.

Ultimately, easily creating reproducible artifacts is great.

But for the sharing story to be complete, the tool also needs to support easily sharing those artifacts, like with a simple command like quarto publish, and hopefully soon a button RStudio that does the same thing.

–> I think that tooling that makes it easy to share what you do with the world on the web is incredibly useful.

–> And it’s not just useful to you, the creator, but to the world, as it facilitates open sharing of knowledge for learning and for reuse.

[Pause]

I’ve been talking just about me and my work so far, but I, like many of you, don’t operate in a silo disconnected from others.

[Mine continue on next slide]

Haciendo un reporte

Componentes de un .qmd

Formatear texto con Markdown

Un documento Quarto se hace con un encabezado, algo de texto y algo de código.

Es fácil dar formato al texto utilizando un lenguaje de marcado llamado markup.

¿Qué es Markdown?

Markdown es un lenguaje de marcado ligero que te permite dar formato al texto utilizando una sintaxis sencilla de texto plano.

Para ponerlo simple, puedes escribir en tu archivo Quarto algo así:

Me *encanta* la función `boxplot()` de R, **muchísimo**.

Y obtendrás este resultado en tu reporte:

Me encanta la función `boxplot()` de R, muchísimo.

Énfasis & Código

• Para poner un texto en negrita, use dos asteriscos ** o guiones bajos __.
• Para poner el texto en cursiva, use un asterisco * o un guión bajo _.
• Para añadir algo relacionado con el código, envuélvalo con back-ticks `.

Encabezados

Para crear un encabezado, añada de uno a seis símbolos # antes del texto del encabezado. El número de # determinará el nivel jerárquico y el tamaño tipográfico del encabezamiento.

Por ejemplo, éste será un título de nivel 1 en su documento:

# Título importante

Y éste un título de nivel 2:

## Un poco menos importante

Links e Imágenes

Para crear un hipervínculo, encierra el texto del enlace entre corchetes [] y la URL entre paréntesis ().

[Visite Google](https://www.google.com)

Para añadir una imagen, se añade un signo de exclamación ! a un hipervínculo.

![Texto alternativo de la imagen](url_imagen)

Listas

Para las listas desordenadas, utilice asteriscos *, más + o menos -.

* Elemento 1 * Elemento 2 * Subelemento 1

Para listas ordenadas, utilice números seguidos de un punto.

1. Primer elemento 2. Segundo elemento

Código

• Los chunks de código empiezan y termina con back-ticks `

```{r}
#| eval: false
#| label: suma
2 + 2
```

• {r} indica el lenguaje de programación en el que queremos que se evalúe el código.
• Entre los tres back-ticks, {r} y los tres back-ticks que cierran, va el código, pero también se pueden escribir opciones chunk de códigos identificadas con un #|.
• También puede haber código en el texto `r `

Más opciones de código

• #| label: es el nombre del chunk.
• #| echo: Controla si se muestra el propio código.
• #| eval: Controla si el código es evaluado.
• #| include: Controla si tanto el código como su salida se incluyen en el documento.
• #| output: Controla si se muestra la salida del código.
• #| warning: false: No se imprimen los warnings, ejemplo: conflicto de versiones.
• #| warning: false: Controla la visualización de los mensajes generados por el código.
• #| error: false: Puede ser usado para hacer que compile el documento incluso si algún chunk tiene problemas.

Tabla de resumen de código

Opción	Código Ejecutado	Código Mostrado	Salida Mostrada
#| echo: false	Sí	No	Sí
#| eval: false	No	Sí	No
#| include: false	Sí	No	No
#| output: false	Sí	Sí	No

Colapsar código en el documento

En este taller, nos centrados en las opciones clave de chucks de código en Quarto que mejoran significativamente la legibilidad del informe. Más allá de estas, hay opciones adicionales para explorar si tienes curiosidad 🤓

Gráficos limpios

Controla el tamaño de tu gráfico

• Quarto permite especificar el tamaño de los gráficos directamente dentro de los parámetros del fragmento de código.

• Se puede controlar tanto el ancho como el alto de una figura usando las opciones fig.width y fig.height. Estas dimensiones se especifican en pulgadas.

```{r}
#| eval: false
#| fig-width: 3
#| fig-height: 3
# Code for a square chart, 3x3 inches
```

• En la web, normalmente tenemos 96 píxeles por pulgada (PPI). Y por defecto, un documento Quarto se renderiza con un ancho de 900 píxeles.

• Por lo tanto, si el gráfico tiene una anchura de 9 pulgadas, ocupará toda la anchura de la página.

Controla el tamaño de tu gráfico

Por favor, consulte los siguientes ejemplos para una mejor comprensión:

• Ancho = 3
• Ancho = 6
• Ancho = 9

Responsividad

• La capacidad de respuesta en el diseño web significa que su contenido, incluidas las figuras, se ajusta al tamaño de la pantalla del dispositivo en el que se está visualizando. Esto es crucial para mantener una experiencia fácil de usar.

• Creanme, habrá gente leyendo el reporte en su teléfono.

• Quarto se destaca en la creación de figuras responsivas automáticamente 🎉. Si el tamaño especificado en pulgadas excede el ancho de la pantalla, Quarto inteligentemente redimensionará la figura para ajustarse al ancho completo de la pantalla mientras mantiene la relación de aspecto original.

Responsividad

• La figura tiene un ancho de 8 pulgadas. Al disminuir la anchura de la pantalla, se ajusta automáticamente para ocupar el 100% de la anchura disponible.

Alineación de figuras

Las distintas preferencias de alineación de las figuras, como izquierda, centro o derecha, pueden gestionarse fácilmente en Quarto mediante los parámetros chunk fig.align = 'left', fig.align = 'center', or fig.align = 'right', respectivamente.

• Izquierda
• Centro
• Derecha

Múltiples figuras

• La visualización de varios gráficos uno al lado del otro es un requisito frecuente para un informe limpio de Quarto. Por defecto, los gráficos generados dentro de un único fragmento de código se muestran uno tras otro verticalmente, consumiendo un espacio considerable en la página.

• Quarto incluye amplias funciones para personalizar la disposición de las figuras. Una de las opciones más sencillas es la función layout-ncol. Permite especificar el número de columnas en las que deben mostrarse los gráficos.

• Una ventaja añadida de este enfoque es su capacidad de respuesta. Cuando se visualizan en pantallas más estrechas, los gráficos se apilan verticalmente de forma automática, lo que garantiza su claridad y legibilidad.

Quarto aplana la curva de aprendizaje

So, in regards to teaching, I’ve talked about a much less steep hill students need to climb as their projects grow. I’ve also said this was a pleasant surprise as it was not something I had thought about when I started teaching with Quarto. But, in hindsight, this was no coincidence. Quarto’s features like consistent citation syntax, more intentional control over when computations should run or rerun, and a single, minimal yaml that controls inputs, layouts, theming, etc. all contribute to flattening this learning curve.

Quarto puede crecer con sus usuarios de una manera profunda

And beyond learners growing and expanding the scope of their work easily with Quarto, Quarto can grow with them in a profound way as well.

–> The fact that Quarto is language and authoring tool independent offers an opportunity for folks to take Quarto with them on their data science journey, wherever that journey takes them. I mean.. I’m almost tempted to finally learn Python to see it in action in Quarto. But who I know is learning Python, and Julia, and other languages are my students in their Computer Science courses. To imagine that they could learn R in RStudio using Quarto in my course, and then continue to use Quarto in Jupyter in their CS courses… That sounds like such a bright future to me!

[Pause] And a bright future includes things we can’t even imagine yet.

[Mine continue on next slide]

Interactividad

Tablas interactivas con DT

Esta es una de mis técnicas preferidas para mostrar Quarto 😍.

Con sólo dos líneas de código adicionales, podés demostrar una tabla interactiva que permite:

• ordenar
• filtrar
• buscar en
• paginación

Esta función es muy útil para mostrar el conjunto de datos de entrada si no es demasiado grande. Ofrece a los lectores la comodidad de acceder a los datos directamente desde el informe.

La magia de esta funcionalidad reside en la biblioteca DT. DT son las siglas de DataTables: la biblioteca JavaScript que hay detrás.

Tablas interactivas con DT

Gráficos interactivos

A esta altura nuestro informe Quarto es un documento HTML, esencialmente un sitio web en miniatura 😳

Gráficos interactivos

Y ahora la parte mágica 🧙

Envuelve tu objeto p en la función ggplotly() de plotly, ¡y tu scatterplot será interactivo!

paula.quarto.pub/hola-quarto

If you would like to start sharing, collaborating, teaching, and reimagining with Quarto by picking up where we left off, go to this link and scroll forward to see the next few slides where we share resources for learning as well as references for the works we presented today. And if you have any questions about Quarto or R Markdown, please stop by the Open Source table in the Lounge between 12-3pm today. And don’t miss the Quarto session at 3:20pm!

Gracias

Thank you so much for joining us this morning, here in person or from wherever you are tuning in to the live stream. We’ve talked about our experiences using Quarto and all the problems it has helped us solve and reimagine, but while Quarto is stable and ready for use, it’s also a baby that you too can be a part of its growth. So start using Quarto, and get involved by asking questions, reporting issues, providing feedback, and even building extensions for it. We can’t wait to see what you create!